The Duckietown project

What is Duckietown?

Goals and objectives

Duckietown is a robotics educations and outreach effort.

The most tangible goal of the project is to provide a low-cost educational platform for learning autonomy, consisting of the Duckiebots, an autonomous robot, and the Duckietowns, the infrastructure in which the Duckiebots navigates.

However, we focus on the learning experience as a whole, by providing a set of modules teaching plans and other guides, as well as a curated role-play experience.

We have two targets:

For instructors, we want to create a “class-in-a-box” that allows to offer a modern and engaging learning experience. Currently, this is feasible at the advanced undergraduate and graduate level, though in the future we would like to present the platform as multi-grade experiences.
For self-guided learners, we want to create a “self-learning experience”, that allows to go from zero knowledge of robotics to graduate-level understanding.

In addition, the Duckietown platform has been used as a research platform.

Learn about the Duckietown educational experience

✎🔗

This video is a Duckumentary about the first version of the class, during Spring 2016. The Duckumentary was shot by Chris Welch.

TODO

The Duckumentary

Learn about the platform

✎🔗

The best way to get a sense of how the platform looks is to watch these videos. They show off the capabilities of the platform.

If you would like to know more, the paper [2] describes the Duckiebot and its software. (With 29 authors, we made the record for a robotics conference!)

add the video here that we showed at ICRA.

Can you do it by night?

Cool Duckietown at night — Cool Duckietown by night

Duckietown history and future

✎🔗

The beginnings of Duckietown

✎🔗

The original Duckietown class was at MIT in 2016.

Part of the first MIT class, during the final demo.

MIT 2.166 Autonomous Vehicles — The need for autonomy

MIT 2.166 "Autonomous Vehicles" - Spring 2016 — The elves of Duckietown

University-level classes in 2016

✎🔗

Later that year, the Duckietown platform was also used in these classes:

NCTU 2016 - Prof. Nick Wang;
RPI 2016 - Prof. John Wen;

University-level classes in 2017

✎🔗

In 2017, these four courses will be taught together, with the students interacting among institutions:

ETH Zürich 2017 - Prof. Emilio Frazzoli, Dr. Andrea Censi;
University of Montreal, 2017 - Prof. Liam Paull;
TTI/Chicago 2017 - Prof. Matthew Walter;
National Chiao Tung University, Taiwan - Prof. Nick Wang’s course;

Furthermore, the Duckietown platform is used also in the following universities:

RPI (Jeff Trinkle)
National Chiao Tung University, Taiwan - Prof. Yon-Ping Chen’s Dynamic system simulation and implementation.
Chosun University, Korea - Prof. Woosuk Sung’s course;
Petra Christian University, Indonesia - Prof. Resmana Lim’s Mobile Robot Design Course
National Tainan Normal University, Taiwan - Prof. Jen-Jee Chen’s Vehicle to Everything (V2X) Course;
Yuan Zhu University, Taiwan - Prof. Kan-Lin Hsiung’s Control course;

Chile

✎🔗

to write

Duckietown High School

✎🔗

to write

First steps

✎🔗

How to get started

✎🔗

If you are an instructor, please jump to Section 3.2.

If you are a self-guided learner, please jump to Section 3.3.

If you are a company, and interested in working with Duckietown, please jump to Section 3.4.

Duckietown for instructors

✎🔗

to write

Duckietown for self-guided learners

✎🔗

to write

Introduction for companies

✎🔗

to write

How to keep in touch

✎🔗

add link to Facebook

add link to Mailing list

add link to Slack?

How to contribute

✎🔗

If you want to contribute to the software…

If you want to contribute to the hardware…

If you want to contribute to the documentation…

If you want to contribute to the dissemination…

Frequently Asked Questions

✎🔗

General questions

✎🔗

What is Duckietown?

Duckietown is a low-cost educational and research platform.

Is Duckietown free to use?

Yes. All materials are released according to an open source license.

Is everything ready?

Not quite! Please sign up to our mailing list to get notified when things are a bit more ready.

How can I start?

See the section First Steps.

How can I help?

If you would like to help actively, please email duckietown@mit.edu.

FAQ by students / independent learners

✎🔗

I want to build my own Duckiebot. How do I get started?

to write

FAQ by instructors

✎🔗

How large a class can it be? I teach large classes.

to write

What is the budget for the robot?

to write

I want to teach a Duckietown class. How do I get started?

Please get in touch with us at duckietown@mit.edu. We will be happy to get you started and sign you up to the Duckietown instructors mailing list.

Why the duckies?

Compared to other educational robotics projects, the presence of the duckies is what makes this project stand out. Why the duckies?

We want to present robotics in an accessible and friendly way.

copy usual discussion from somewhere else.

add picture of kids with Duckiebots.

Accounts

✎🔗

Complete list of accounts

✎🔗

Currently, Duckietown has the following accounts:

Github: for source code, and issue tracking;
Slack: a forum for wide communication;
Twist: to be used for instructors coordination;
Google Drive: to be used for instructors coordination, maintaining TODOs, etc;
Dropbox Folders (part of Andrea’s personal accounts): to be abandoned;
Vimeo, for storing the videos;
The duckietown-teaching mailing list, for low-rate communication with instructors;
We also have a list of addresses, of people signed up on the website, that we didn’t use yet;
The Facebook page.

For other contributors

✎🔗

If you are an international contributor:

Sign up on Slack, to keep up with the project.
(optional) Get Github permissions if you do frequent updates to the repositories.

How to contribute to Duckietown

✎🔗

Contributing to the documentation

✎🔗

Where the documentation is

✎🔗

All the documentation is in the repository duckietown/duckuments.

The documentation is written as a series of small files in Markdown format.

It is then processed by a series of scripts to create this output:

Editing links

✎🔗

The simplest way to contribute to the documentation is to click any of the “✎” icons next to the headers.

They link to the “edit” page in Github. There, one can make and commit the edits in only a few seconds.

Comments

✎🔗

In the multiple-page version, each page also includes a comment box powered by a service called Disqus. This provides a way for people to write comments with a very low barrier. (We would periodically remove the comments.)

Installing the documentation system

✎🔗

In the following, we are going to assume that the documentation system is installed in ~/duckuments. However, it can be installed anywhere.

We are also going to assume that you have setup a Github account with working public keys.

Dependencies

✎🔗

On Ubuntu 16.04, these are the dependencies to install:

$ sudo apt install libxml2-dev libxslt1-dev
$ sudo apt install libffi6 libffi-dev
$ sudo apt install python-dev python-numpy python-matplotlib
$ sudo apt install virtualenv

Download the `duckuments` repo

✎🔗

Download the duckietown/duckuments repository in that directory:

$ git clone git@github.com:duckietown/duckuments ~/duckuments

Setup the virtual environment

✎🔗

Next, we will create a virtual environment using inside the ~/duckuments directory.

Change into that directory:

$ cd ~/duckuments

Create the virtual environment using virtualenv:

$ virtualenv --system-site-packages deploy

Other distributions: In other distributions you might need to use venv instead of virtualenv.

Activate the virtual environment:

$ source ~/duckuments/deploy/bin/activate

Setup the `mcdp` external repository

✎🔗

Make sure you are in the directory:

$ cd ~/duckuments

Clone the mcdp external repository, with the branch duckuments.

$ git clone -b duckuments git@github.com:AndreaCensi/mcdp

Install it and its dependencies:

$ cd ~/duckuments/mcdp
$ python setup.py develop

If you get a permission error here, it means you have not properly activated the virtual environment.

Other distributions: If you are not on Ubuntu 16, depending on your system, you might need to install these other dependencies:

$ pip install numpy matplotlib

Compiling the documentation

✎🔗

Make sure you have deployed and activated the virtual environment. You can check this by checking which python is active:

$ which python
/home/user/duckuments/deploy/bin/python

Then:

$ cd ~/duckuments
$ make duckuments-dist

This creates the directory duckuments-dist, which contains another checked out copy of the repository, but with the branch gh-pages, which is the branch that is published by Github using the “Github Pages” mechanism.

At this point, please make sure that you have these two .git folders:

~/duckuments/.git
~/duckuments/duckuments-dist/.git

To compile the docs, run make clean compile:

$ make clean compile

To see the result, open the file

./duckuments-dist/master/duckiebook/index.html

Incremental compilation

✎🔗

If you want to do incremental compilation, you can omit the clean and just use:

$ make compile

This will be faster. However, sometimes it might get confused. At that point, do make clean.

Troubleshooting compilation

✎🔗

“Invalid XML”

“Markdown” doesn’t mean that you can put anything in a file. Except for the code blocks, it must be valid XML. For example, if you use “>” and “<” without quoting, it will likely cause a compile error.

“Tabs are evil”

Do not use tab characters. The error message in this case is quite helpful in telling you exactly where the tabs are.

The error message contains ValueError: Suspicious math fragment 'KEYMATHS000ENDKEY'

You probably have forgotten to indent a command line by at least 4 spaces. The dollar in the command line is now being confused for a math formula.

The workflow to edit documentation.

✎🔗

This is the workflow:

Edit the Markdown in the master branch of the duckuments repository.
Run make compile to make sure it compiles.
Commit the Markdown and push on the master branch.

Done. A bot will redo the compilation and push the changes in the gh-pages branch.

Step 2 is there so you know that the bot will not encounter errors.

*Deploying the documentation

✎🔗

This part is now done by a bot, so you don’t need to do it manually.

To deploy the documentation, jump into the DUCKUMENTS/duckuments-dist directory.

Run the command git branch. If the out does not say that you are on the branch gh-pages, then one of the steps before was done incorrectly.

$ cd $DUCKUMENTS/duckuments-dist
$ git branch
...
* gh-pages
...

Now, after triple checking that you are in the gh-pages branch, you can use git status to see the files that were added or modified, and simply use git add, git commit and git push to push the files to Github.

*Compiling the PDF version

✎🔗

The dependencies below are harder to install. If you don’t manage to do it, then you only lose the ability to compile the PDF. You can do make compile to compile the HTML version, but you cannot do make compile-pdf.

Installing `nodejs`

✎🔗

Ensure the latest version (>6) of nodejs is installed.

Run:

$ nodejs --version
6.xx

If the version is 4 or less, remove nodejs:

$ sudo apt remove nodejs

Install nodejs using the instructions at this page.

Next, install the necessary Javascript libraries using npm:

$ cd $DUCKUMENTS
$ npm install MathJax-node jsdom@9.3 less

Troubleshooting `nodejs` installation problems

✎🔗

The only pain point in the installation procedure has been the installation of nodejs packages using npm. For some reason, they cannot be installed globally (npm install -g).

Do not use sudo for installation. It will cause problems.

If you use sudo, you probably have to delete a bunch of directories, such as: RBROOT/node_modules, ~/.npm, and ~/.node_modules, if they exist.

Installing Prince

✎🔗

Install PrinceXML from this page.

Installing fonts

✎🔗

Download STIX fonts from this site.

Unzip and copy the ttf to ~/.fonts:

$ cp -R STIXv2.0.0 ~/.fonts

and then rebuild the font cache using:

$ fc-cache -fv

Compiling the PDF

✎🔗

To compile the PDF, use:

$ make compile-pdf

This creates the file:

./duckuments-dist/master/duckiebook.pdf

Features of the documentation writing system

✎🔗

The Duckiebook is written in a Markdown dialect. A subset of LaTeX is supported.

There are also some additional features that make it possible to create publication-worthy materials.

Embedded LaTeX

✎🔗

You can use $\LaTeX$ math, environment, and references. For example, take a look at

$$ x^2 = \int_0^t f(\tau)\ \text{d}\tau $$

or refer to Proposition 1.

Proposition example This is an example proposition: $2x = x + x$.

The above was written as in Listing 1.

You can use $\LaTeX$ math, environment, and references.
For example, take a look at

\[
    x^2 = \int_0^t f(\tau)\ \text{d}\tau
\]

or refer to [](#prop:example).

\begin{proposition}[Proposition example]\label{prop:example}
This is an example proposition: $2x = x + x$.
\end{proposition}

Use of LaTeX code.

other LaTeX features supported

LaTeX symbols

✎🔗

The LaTeX symbols definitions are in a file called docs/symbols.tex.

Put all definitions there; if they are centralized it is easier to check that they are coherent.

Variables in command lines and command output

✎🔗

Use the syntax “![name]” for describing the variables in the code.

For example, to obtain:

$ ssh robot name.local

Use the following:


For example, to obtain:

    $ ssh ![robot name].local

Make sure to quote (with 4 spaces) all command lines. Otherwise, the dollar symbol confuses the LaTeX interpreter.

Character escapes

✎🔗

Use the string $ to write the dollar symbol $, otherwise it gets confused with LaTeX math materials. Also notice that you should probably use “USD” to refer to U.S. dollars.

Other symbols to escape are shown in Table 1.

Symbols to escape

use `$`	instead of `$`
use ```	instead of `
use `&#lt;`	instead of `<`
use `&#gt;`	instead of `>`

Keyboard keys

✎🔗

Use the kbd element for keystrokes.

For example, to obtain:

Press a then Ctrl-C.

use the following:

Press <kbd>a</kbd> then <kbd>Ctrl</kbd>-<kbd>C</kbd>.

Figures

✎🔗

For any element, adding an attribute called figure-id with value fig:figure ID or tab:table ID will create a figure that wraps the element.

For example:

<div figure-id="fig:figure ID">
    figure content
</div>

It will create HMTL of the form:

<div id='fig:code-wrap' class='generated-figure-wrap'>
    <figure id='fig:figure ID' class='generated-figure'>
        <div>
            figure content
        </div>
    </figure>
</div>

To add a caption, add an attribute figure-caption:

<div figure-id="fig:figure ID" figure-caption="This is my caption">
    figure content
</div>

Alternatively, you can put anywhere an element figcaption with ID figure id:caption:

<element figure-id="fig:figure ID">
    figure content
</element>

<figcaption id='fig:figure ID:caption'>
    This the caption figure.
</figcaption>

To refer to the figure, use an empty link:

Please see [](#fig:figure ID).

The code will put a reference to “Figure XX”.

Subfigures

✎🔗

You can also create subfigures, using the following syntax.

<div figure-id="fig:big">
    <figcaption>Caption of big figure</figcaption>

    <div figure-id="subfig:first">
        <figcaption>Caption 1</figcaption>
        <p>Content of first subfig</p>
    </div>

    <div figure-id="subfig:second">
        <figcaption>Caption 2</figcaption>
        <p>Content of second subfig</p>
    </div>
</div>

Content of first subfig

Caption 1

Content of second subfig

Caption 2

Caption of big figure

Shortcut for tables

✎🔗

The shortcuts col2, col3, col4, col5 are expanded in tables with 2, 3, 4 or 5 columns.

The following code:


<col2 figure-id="tab:mytable" figure-caption="My table">
    <span>A</span>
    <span>B</span>
    <span>C</span>
    <span>D</span>
</col2>

gives the following result:

My table

A	B
C	D

`labels-row1` and `labels-row1`

✎🔗

Use the classes labels-row1 and labels-row1 to make pretty tables like the following.

labels-row1: the first row is the headers.

labels-col1: the first column is the headers.

Using class="labels-col1"

header A	B	C	1
header D	E	F	2
header G	H	I	3

Using class="labels-row1"

header A	header B	header C
D	E	F
G	H	I
1	2	3

Linking to documentation from inside and outside the documentation

✎🔗

Establishing names of headers

✎🔗

You give IDs to headers using the format:

### header title {#topic ID}

For example, for this subsection, we have used:

### Establishing names of headers {#establishing}

With this, we have given this header the ID “establishing”.

Linking from the documentation to the documentation

✎🔗

You can use the syntax:

[](#topic ID)

to refer to the header.

You can also use some slightly more complex syntax that also allows to link to only the name, only the number or both (Table 5).

Syntax for referring to sections.

See [](#establishing).

See Subsection 6.9.1

See <a class="only_name" href="#establishing"></a>.

See Establishing names of headers.

See <a class="only_number" href="#establishing"></a>.

See 6.9.1.

See <a class="number_name" href="#establishing"></a>.

See Subsection 6.9.1 - Establishing names of headers.

Linking to the documentation from outside the documentation

✎🔗

You are encouraged to put links to the documentation from the code or scripts.

To do so, use links of the form:

http://purl.org/dth/topic ID

Here “dth” stands for “Duckietown Help”. This link will get redirected to the corresponding document on the website.

For example, you might have a script whose output is:

$ rosrun mypackage myscript
Error. I cannot find the scuderia file.
See: http://purl.org/dth/scuderia

When the user clicks on the link, they will be redirected to Section 90.2.

Embedding videos

✎🔗

It is possible to embed Vimeo videos in the documentation.

Do not upload the videos to your personal Vimeo account; they must all be posted to the Duckietown Engineering account.

This is the syntax:

<dtvideo src="vimeo:vimeo ID"/>

For example, this code:

<div figure-id="fig:example-embed">
    <figcaption>Cool Duckietown by night</figcaption>
    <dtvideo src="vimeo:152825632"/>
</div>

produces this result:

Depending on the output media, the result will change:

On the online book, the result is that a player is embedded.
On the e-book version, the result is that a thumbnail is produced, with a link to the video;
On the deadtree version, a thumbnail is produced with a QR code linking to the video (TODO).

Documentation style guide

✎🔗

This chapter describes the conventions for writing the technical documentation.

General guidelines for technical writing

✎🔗

The following holds for all technical writing.

The documentation is written in correct English.
Do not say “should” when you mean “must”. “Must” and “should” have precise meanings and they are not interchangeable. These meanings are explained in this document.
“Please” is unnecessary in technical documentation.

“Please remove the SD card.”

“Remove the SD card”.

Do not use colloquialisms or abbreviations.

“The pwd is ubuntu.”

“The password is ubuntu.”

Do not use emojis.
Do not use ALL CAPS.
Make infrequent use of bold statements.
Do not use exclamation points.

Style guide for the Duckietown documentation

✎🔗

It’s ok to use “it’s” instead of “it is”, “can’t” instead of “cannot”, etc.
All the filenames and commands must be enclosed in code blocks using Markdown backticks.

“Edit the ~/.ssh/config file using vi.”

“Edit the ~/.ssh/config file using vi.”

Ctrl-C, ssh etc. are not verbs.

“Ctrl-C from the command line”.

“Use Ctrl-C from the command line”.

Subtle humor and puns about duckies are encouraged.

Writing command lines

✎🔗

Use either “laptop” or “duckiebot” (not capitalized, as a hostname) as the prefix for the command line.

For example, for a command that is supposed to run on the laptop, use:

laptop $ cd ~/duckietown

It will become:

laptop $ cd ~/duckietown

For a command that must run on the Duckiebot, use:

duckiebot $ cd ~/duckietown

It will become:

duckiebot $ cd ~/duckietown

If the command is supposed to be run on both, omit the hostname:

$ cd ~/duckietown

Frequently misspelled words

✎🔗

“Duckiebot” is always capitalized.
Use “Raspberry Pi”, not “PI”, “raspi”, etc.
These are other words frequently misspelled:

5 GHz WiFi

Other conventions

✎🔗

When the user must edit a file, just say: “edit /this/file”.

Writing down the command line for editing, like the following:

$ vi /this/file

is too much detail.

(If people need to be told how to edit a file, Duckietown is too advanced for them.)

Troubleshooting sections

✎🔗

Write the documentation as if every step succeeds.

Then, at the end, make a “Troubleshooting” section.

Organize the troubleshooting section as a list of symptom/resolution.

The following is an example of a troubleshooting section.

Troubleshooting

✎🔗

This strange thing happens.

Maybe the camera is not inserted correctly. Remove and reconnect.

This other strange thing happens.

Maybe the plumbus is not working correctly. Try reformatting the plumbus.

Knowledge graph

✎🔗

Formalization

✎🔗

Atoms

✎🔗

Atom An atom is a concrete resource (text, video) that is the smallest unit that is individually addressable. It is indivisible.

Each atom as a type, as follows:

text
  text/theory
  text/setup
  text/demo
  text/exercise
  text/reference
  text/instructor-guide
  text/quiz
video
  video/lecture
  video/instructable
  video/screencast
  video/demo

Semantic graph of atoms

✎🔗

Atoms form a directed graph, called “semantic graph”.

Each node is an atom.

The graph has four different types of edges:

“Requires” edges describe a strong dependency: “You need to have done this. Otherwise it will not work.”
“Recommended” edges describe a weaker dependency; it is not strictly necessary to have done that other thing, but it will significantly improve the result of this.
“Reference” edges describe background information. “If you don’t know / don’t remember, you might want to see this”
“See also” edges describe interesting materials for the interested reader. Completely optional; it will not impact the result of the current procedure.

Modules

✎🔗

A “module” is an abstraction from the point of view of the teacher.

Module A module is a directed graph, where the nodes are either atoms or other modules, and the edges can be of the four types described in Subsection 8.1.2.

Because modules can contain other modules, they allow to describe hierarchical contents. For example, a class module is a module that contains other modules; a “degree” is a module that contains “class” modules, etc.

Modules can overlap. For example, a “Basic Object Detection” and an “Advanced Object Detection” module might have a few atoms in common.

Atoms properties

✎🔗

Each atom has the following properties:

An ID (alphanumeric + - and ‘_’). The ID is used for cross-referencing. It is the same in all languages.
A type, as above.

There might be different versions of each atom. This is used primarily for dealing with translations of texts, different representations of the same image, Powerpoint vs Keynote, etc.

A version is a tuple of attributes.

The attributes are:

Language: A language code, such as en-US (default), zh-CN, etc.
Mime type: a MIME type.

Each atom version has:

A status value: one of draft, beta, ready, to-update (Table 6).
A human-readable title.
A human-readable summary (1 short paragraph).

Status codes

`draft`	We just started working on it, and it is not ready for public consumption.
`beta`	Early reviewers should look at it now.
`ready`	The document is ready for everybody.
`to-update`	A new pass is needed on this document, because it is not up to date anymore.

Markdown format for text-like atoms

✎🔗

For the text-like resources, they are described in Markdown files.

The name of the file does not matter.

All files are encoded in UTF-8.

Each file starts with a H1 header. The contents is the title.

The header has the following attributes:

The ID. ({#ID})
The language is given by an attribute lang ({lang=en-US}).
The type is given by an attribute type ({type=demo}).
The status is given by an attribute status ({status=draft}).

Here is an example of a header with all the attributes:

# Odometry calibration {#odometry-calibration lang=en-US type='text/theory' status=ready}

This first paragraph will be used as the "summary" for this text.

calibration.en.md

And this is how the Italian translation would look like:

# Calibrazione dell'odometria {#odometry-calibration lang=it type='text/theory' status=draft}

Questo paragrafo sarà usato come un sommario del testo.

calibration.it.md

How to describe the semantic graphs of atoms

✎🔗

In the text, you describe the semantic graph using tags and IDs.

In Markdown, you can give IDs to sections using the syntax:

# Setup step 1  {#setup-step1}

This is the first setup step.

Then, when you write the second step, you can add a a semantic edge using the following.

# Setup step 2  {#setup-step2}

This is the second setup step.

Requires: You have completed the first step in [](#setup-step1).

The following table describes the syntax for the different types of semantic links:

Semantic links

Requires	`Requires: You need to have done [](#setup-step).`
Recommended	`Recommended: It is better if you have setup Wifi as in [](#setup-wifi).`
Reference	`Reference: For more information about rostopic, see [](#rostopic).`
See also	`See also: If you are interested in feature detection, you might want to learn about [SIFT](#SIFT).`

How to describe modules

✎🔗

Define a micro-format for this.

Basic Markdown Reference

✎🔗

Andrea

To write

Operation manual - Duckiebot

✎🔗

Duckiebot configurations

✎🔗

Configuration list

✎🔗

Define here all the configurations that we use.

Configuration D17-0: Only camera and motors.

Configuration D17-0+w: Previous one + an additional WiFi card (Edimax).

Configuration D17-0+j: Previous one + joystick.

Configuration D17-1: LED lights and bumpers

Configuration functionality

✎🔗

What can each configuration do?

Acquiring the parts for the Duckiebot `C0`

✎🔗

The trip begins with acquiring the parts. Here, we provide a link to all bits and pieces that are needed to build a Duckiebot, along with their price tag.

In general, keep in mind that:

The links might expire, or the prices might vary.
Shipping times and fees vary, and are not included in the prices shown below.
Substitutions are OK for the mechanical components, and not OK for all the electronics, unless you are OK in writing some software.
Buying the parts for more than one Duckiebot makes each one cheaper than buying only one.

Resources necessaries:

Cost: USD 193.50 + Shipping Fees (configuration D17-0)
Time: 15 days (average shipping for cheapest choice of components)

Results:

A kit of parts ready to be assembled.

Add a different “Tools” section in the table (e.g., solderer), or add in the resoruces beginning snippet; Differentiate pricing for bulk vs detail purchase (?)

Bill of materials

✎🔗

Bill of materials

Chassis	USD 20
Camera with 160-FOV Fisheye Lens	USD 22
Camera Mount	USD 8.50
300mm Camera Cable	USD 2
Raspberry Pi 3 - Model B	USD 35
Heat Sinks	USD 5
Power supply	USD 7.50
16 GB Class 10 MicroSD Card	USD 20
Mirco SD card reader	USD 6
Tiny 32GB USB Flash Drive	USD 12.50
Stepper Motor HAT	USD 22.50
Stacking Headers 2 for `D17-1`, 1 otherwise	USD 2.50/piece
Battery	USD 20
16 Nylon Standoffs (M2.5 12mm F 6mm M	USD 0.05/piece
4 Nylon Hex Nuts (M2.5)	USD 0.02/piece
4 Nylon Screws (M2.5x10)	USD 0.05/piece
2 Zip Ties (300x5mm)	USD 8.99
Wifi Augmenter (`D17-0+w`)	USD 20
Joypad (`D17-0+j`)	USD 10.50
20 Female-Female Jumper Wires (300mm) (`D17-1`)	USD 8
Male-Male Jumper Wire (150mm) (`D17-1`)	USD 1.95
LEDs (`D17-1`)	USD 10
LED HAT (`D17-1`)	USD 28.20 for 3 pieces
PWM/Servo HAT (`D17-1`)	USD 17.50
40 pin female header (`D17-1`)	USD 1.50
Bumpers (`D17-1`)	TBD (custom made)
5 4 pin female header (`D17-1`)	USD 0.60/piece
2 16 pin male header (`D17-1`)	USD 0.61/piece
12 pin male header (`D17-1`)	USD 0.48/piece
3 pin male header (`D17-1`)	USD 0.10/piece
2 pin female shunt jumper (`D17-1`)	USD 2/piece
5 200 Ohm resistors (`D17-1`)	USD 0.10/piece
10 130 Ohm resistors (`D17-1`)	USD 0.10/piece
Total for `D17-0` configuration	USD 191.50
Total for `D17-0+w` configuration	USD 211.50
Total for `D17-0+j` configuration	USD 222
Total for `D17-1` configuration	USD 281+Bumpers

Chassis

✎🔗

We selected the Magician Chassis as the basic chassis for the robot (Figure 11).

We chose it because it has a double-decker configuration, and so we can put the battery in the lower part.

The chassis pack includes the motors and wheels as well as the structural part.

The price for this in the US is about USD 15-30.

Raspberry Pi 3 - Model B (RPI-3)

✎🔗

The RPI-3 is the central computer of the Duckiebot. Duckiebot version D17 uses Model B (Figure 12) (A1.2GHz 64-bit quad-core ARMv8 CPU, 1GB RAM), a small but powerful computer.

The price for this in the US is about USD 35.

Power Supply

✎🔗

We want a hard-wired power source (5VDC, 2.4A, Micro USB) to supply the RPI-3 (Figure 13).

The price for this in the US is about USD 5-10.

Heat Sinks

✎🔗

The RPI-3 will heat up significantly during use. It is warmly recommended to add heat sinks, as in Figure 14. Since we will be stacking HATs on top of the RPI-3 with 15 mm standoffs, the maximum height of the heat sinks should be well below 15 mm. The chip dimensions are 15x15 mm and 10x10 mm.

Class 10 MicroSD Card

✎🔗

The MicroSD card (Figure 15) is the hard disk of the RPI-3. 16 Gigabytes of capacity are sufficient for the system image.

Mirco SD card reader

✎🔗

A MicroSD card reader (Figure 16) is useful to copy the system image to a Duckiebot from a computer to the RPI-3 microSD card, when the computer does not have a native SD card slot.

Tiny 32GB USB Flash Drive

✎🔗

This “external” hard drive (Figure 17) is very convenient to store logs during experiments and later port them to a workstation for analysis. It provides storage capacity and faster data transfer than the MicroSD card.

Camera

✎🔗

The Camera is the main sensor of the Duckiebot. Version D17 equips a 5 Mega Pixels 1080p camera with wide field of view ($160^\circ$) fisheye lens (Figure 18).

Camera Mount

✎🔗

The camera mount (Figure 19) serves to keep the camera looking forward at the right angle to the road (looking slightly down). The front cover is not essential.

300mm Camera Cable

✎🔗

A longer (300 mm) camera cable Figure 20 make assembling the Duckiebot easier, allowing for more freedom in the relative positioning of camera and computational stack.

Wifi Augmenter

✎🔗

The Edimax AC1200 EW-7822ULC wifi adpater (Figure 21) boosts the connectivity of the Duckiebot, especially useful in busy Duckietowns (e.g., classroom).

The Edimax AC1200 EW-7822ULC wifi adapter

Joypad

✎🔗

The joypad is used to manually remote control the Duckiebot. Any 2.4 GHz wireless controller (with a tiny USB dongle) will do.

The model link in the table (Figure 22) does not include batteries (2 AA 1.5V)!

DC Stepper Motor HAT

✎🔗

We use the DC Stepper motor HAT (Figure 22) to control the DC motors that drive the wheels. This item will require soldering to be functional.

Stacking Headers

✎🔗

We use long 20x2 stacking headers (Figure 24) to connect the RPI-3 with the other HATs, creating a stack. This item will require soldering to be functional.

In configuration D17-1, we need 2 stacking headers.

In all configurations, we use only 1 stacking header.

Battery

✎🔗

The battery (Figure 25) provides power to the Duckiebot.

We choose this battery because it has a good combination of size (to fit in the lower deck of the Magician Chassis), high output amperage (2.4A and 2.1A at 5V DC) over two USB outputs, a good capacity (10400 mAh) at an affordable price (USD 20).

Standoffs, Nuts and Screws

✎🔗

We use non electrically conductive standoffs (M2.5 12mm F 6mm M), nuts (M2.5), and screws (M2.5x10mm) to hold the RPI-3 to the chassis and the HATs stacked on top of the RPI-3.

In configuration D17-0 and D17-0+w or D17-0+j, the Duckiebot requires 8 standoffs, 4 nuts and 4 screws.

In configuration D17-1, the Duckiebot requires 16 standoffs, 4 nuts and 4 screws.

Zip Tie

✎🔗

Two 300x5mm zip ties are going to be useful to keep the battery at the lower deck from moving around.

LEDs

✎🔗

In configuration D17-1, the Duckiebot is equipped with 5 RGB LEDs. LEDs can be used to signal to other Duckiebots, or just make cool patterns!

The pack of LEDs linked in the table above holds 10 LEDs, enough for two Duckiebots.

LED HAT

✎🔗

In configuration D17-1, the LED HAT (Figure 29) provides an interface for our RGB LEDs and the computational stack. This board is a daughterboard for the Adafruit 16-Channel PWM/Servo HAT, and enables connection with additional gadgets such as ADS1015 12 Bit 4 Channel ADC, Monochrome 128x32 I2C OLED graphic display, and Adafruit 9-DOF IMU Breakout - L3GD20H+LSM303. This item will require soldering to be functional.

This board is custom degined and can only be ordered in minimum runs of 3 pieces. The price scales down quickly with quantity, and lead times may be significant, so it is better to buy these boards in bulk.

PWM/Servo HAT

✎🔗

In configuration D17-1, the PWM/Servo HAT HAT (Figure 30) mates to the LED HAT and provides the signals to control the LEDs, without taking computational resources away from the Rasperry Pi itself. This item will require soldering to be functional.

Male-Male Jumper Wires

✎🔗

In configuration D17-1, the Duckiebot requires one male-male jumper wire (Figure 31) to power the DC Stepper Motor HAT from the PWM/Servo HAT.

Female-Female Jumper Wires

✎🔗

In configuration D17-1, 20 Female-Female Jumper Wires (Figure 32) are necessary to connect 5 LEDs to the LED HAT.

Bumpers

✎🔗

These bumpers are designed to keep the LEDs in place and are therefore used only in configuration D17-1. They are custom designed parts, so they must be produced and cannot be bought. We used laser cutting facilities. Our design files are available [here].

add links to .sldprt files once confirmed final version

Passive Electric Components

✎🔗

5 4 pin female header

2 16 pin male header

1 12 pin male header

1 3 pin male header

1 2 pin female shunt jumper

5 200 Ohm resistors

10 130 Ohm resistors

These items will require soldering to be functional.

Clean up

Soldering boards for `C0`

✎🔗

Shiying

Resources necessaries:

…
Time: ??? minutes

Results:

…

finish above

Assembling the Duckiebot `C0`

✎🔗

Shiying

Resources necessaries:

Duckiebot D17-C0 parts.

The acquisition process is explained in Chapter 11.

Time: about ??? minutes.

Results:

An assembled Duckiebot in configuration D17-C0.

Shiying: here will be the instruction about assembling the Duckiebot. :-)

Reproducing the image

✎🔗

Andrea

These are the instructions to reproduce the Ubuntu image that we use.

Please note that the image is already available, so you don’t need to do this manually.

However, this documentation might be useful if you would like to port the software to a different distribution.

Resources necessaries:

Internet connection to download the packages.
A PC running any Linux with an SD card reader.
Time: about 20 minutes.

Results:

A baseline Ubuntu Mate 16.04.2 image with updated software.

Download and uncompress the Ubuntu Mate image

✎🔗

Download the image from the page

https://ubuntu-mate.org/download/

The file we are looking for is:

filename: ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
    size: 1.2 GB
  SHA256: dc3afcad68a5de3ba683dc30d2093a3b5b3cd6b2c16c0b5de8d50fede78f75c2

After download, run the command sha256sum to make sure you have the right version:

laptop $ sha256sum ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz
dc3afcad68a5de3ba683dc30d2093a3b5b3cd6b2c16c0b5de8d50fede78f75c2

If the string does not correspond exactly, your download was corrupted. Delete the file and try again.

Then decompress using the command xz:

laptop $ xz -d ubuntu-mate-16.04.2-desktop-armhf-raspberry-pi.img.xz

Burn the image to an SD card

✎🔗

Next, burn the image on to the SD card.

This procedure is explained in Section 78.1.

Verify that the SD card was created correctly

✎🔗

Remove the SD card and plug it in again in the laptop.

Ubuntu will mount two partitions, by the name of PI_ROOT and PI_BOOT.

Installation

✎🔗

Boot the disk in the Raspberry Pi.

Choose the following options:

language: English
username: ubuntu
password: ubuntu
hostname: duckiebot

Choose the option to log in automatically.

Reboot.

Update installed software

✎🔗

The WiFi was connected to airport network duckietown with password quackquack.

Afterwards I upgraded all the software preinstalled with these commands:

duckiebot $ sudo apt update
duckiebot $ sudo apt dist-upgrade

Expect dist-upgrade to take quite a long time (up to 2 hours).

Raspberry Pi Config

✎🔗

The Raspberry Pi is not accessible by SSH by default.

Run raspi-config:

duckiebot $ sudo raspi-config

choose “3. Interfacing Options”, and enable SSH,

We need to enable the camera and the I2C bus.

choose “3. Interfacing Options”, and enable camera, and I2C.

Also disable the graphical boot

Install packages

✎🔗

Install these packages.

Etckeeper:

duckiebot $ sudo apt install etckeeper

Editors / shells:

duckiebot $ sudo apt install -y vim emacs byobu zsh

Git:

duckiebot $ sudo apt install -y git git-extras

Other:

duckiebot $ sudo apt install htop atop nethogs iftop
duckiebot $ sudo apt install aptitude apt-file

Development:

duckiebot $ sudo apt install -y build-essential libblas-dev liblapack-dev libatlas-base-dev gfortran libyaml-cpp-dev

Python:

duckiebot $ sudo apt install -y python-dev ipython python-sklearn python-smbus
duckiebot $ sudo apt install -y python-termcolor
duckiebot $ sudo pip install scipy --upgrade

I2C:

duckiebot $ sudo apt install -y i2c-tools

Install Edimax driver

✎🔗

First, mark the kernel packages as not upgradeable:

$ sudo apt-mark hold raspberrypi-kernel raspberrypi-kernel-headers
raspberrypi-kernel set on hold.
raspberrypi-kernel-headers set on hold

Then, download and install the Edimax driver from this repository.

$ git clone git@github.com:duckietown/rtl8822bu.git
$ cd rtl8822bu
$ make
$ sudo make install

Install ROS

✎🔗

Install ROS.

The procedure is given in Section 93.1.

Wireless configuration (old version)

✎🔗

This is the old version.

There are two files that are important to edit.

The file /etc/network/interfaces should look like this:

# interfaces(5) file used by ifup(8) and ifdown(8)
# Include files from /etc/network/interfaces.d:
#source-directory /etc/network/interfaces.d

auto wlan0

# The loopback network interface
auto lo
iface lo inet loopback

# Wireless network interface
allow-hotplug wlan0
iface wlan0 inet dhcp
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
iface default inet dhcp

The file /etc/wpa_supplicant/wpa_supplicant.conf should look like this:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
ssid="duckietown"
psk="quackquack"
proto=RSN
key_mgmt=WPA-PSK
pairwise=CCMP
auth_alg=OPEN
}
network={
   key_mgmt=NONE
}

Wireless configuration

✎🔗

The files that describe the network configuration are in the directory

/etc/NetworkManager/system-connections/

This is the contents of the connection file duckietown, which describes how to connect to the duckietown wireless network:

[connection]
id=duckietown
uuid=e9cef1bd-f6fb-4c5b-93cf-cca837ec35f2
type=wifi
permissions=
secondaries=
timestamp=1502254646

[wifi]
mac-address-blacklist=
mac-address-randomization=0
mode=infrastructure
ssid=duckietown

[wifi-security]
group=
key-mgmt=wpa-psk
pairwise=
proto=
psk=quackquack

[ipv4]
dns-search=
method=auto

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
ip6-privacy=0
method=auto

This is the file

/etc/NetworkManager/system-connections/create-5ghz-network

Contents:

[connection]
id=create-5ghz-network
uuid=7331d1e7-2cdf-4047-b426-c170ecc16f51
type=wifi
# Put the Edimax interface name here:
interface-name=wlx74da38c9caa0 - to change
permissions=
secondaries=
timestamp=1502023843

[wifi]
band=a
# Put the Edimax MAC address here
mac-address=74:DA:38:C9:CA:A0 - to change
mac-address-blacklist=
mac-address-randomization=0
mode=ap
seen-bssids=
ssid=duckiebot-not-configured

[ipv4]
dns-search=
method=shared

[ipv6]
addr-gen-mode=stable-privacy
dns-search=
ip6-privacy=0
method=ignore

Note that there is an interface name and MAC address that need to be changed on each PI.

SSH server config

✎🔗

This enables the SSH server:

$ sudo systemctl enable ssh

Create swap Space

✎🔗

Do the following:

Create an empty file using the dd (device-to-device copy) command:

duckiebot $ sudo dd if=/dev/zero of=/swap0 bs=1M count=512

This is for a 512 MB swap space.

Format the file for use as swap:

duckiebot $ sudo mkswap /swap0

Add the swap file to the system configuration:

duckiebot $ sudo vi /etc/fstab

Add this line to the bottom:

/swap0 swap swap

Activate the swap space:

duckiebot $ sudo swapon -a

Passwordless sudo

✎🔗

First, make vi the default editor, using

$ sudo update-alternatives --config editor

and then choose vim.basic.

Then run:

$ sudo visudo

And then change this line:

%sudo   ALL=(ALL:ALL) ALL

into this line:

%sudo   ALL=(ALL:ALL) NOPASSWD:ALL

Clean up

✎🔗

You can use the command dpigs to find out which packages take lots of space.

sudo apt install wajig  debian-goodies

Either:

$ wajig large
$ dpigs -H -n 20

Stuff to remove:

$ sudo apt remove thunderbird
$ sudo apt remove libreoffice-\*
$ sudo apt remove openjdk-8-jre-headless
$ sudo apt remove fonts-noto-cjk
$ sudo apt remove brasero

At the end, remove extra dependencies:

$ sudo apt autoremove

And remove the apt cache using:

$ sudo apt clean

The total size should be around 6.6GB.

Ubuntu user configuration

✎🔗

Groups

✎🔗

You should make the ubuntu user belong to the i2c and input groups:

duckiebot $ sudo adduser ubuntu i2c
duckiebot $ sudo adduser ubuntu input

: forgot to add to aug20 image:

duckiebot $ sudo adduser ubuntu video

You may need to do the following (but might be done already through raspi-config):

duckiebot $ sudo udevadm trigger

Basic SSH config

✎🔗

Do the basic SSH config.

The procedure is documented in Section 80.3.

this is not in the aug10 image.

Passwordless SSH config

✎🔗

Add .authorized_keys so that we can all do passwordless SSH.

The key is at the URL

https://www.dropbox.com/s/pxyou3qy1p8m4d0/duckietown_key1.pub?dl=1

Download to .ssh/authorized_keys:

duckiebot $ curl -o .ssh/authorized_keys URL above

Shell prompt

✎🔗

Add the following lines to ~ubuntu/.bashrc:

echo ""
echo "Welcome to a duckiebot!"
echo ""
echo "Reminders:"
echo ""
echo "1) Do not use the user 'ubuntu' for development - create your own user."
echo "2) Change the name of the robot from 'duckiebot' to something else."
echo ""

export EDITOR=vim

Check that all required packages were installed

✎🔗

At this point, before you copy/distribute the image, create a user, install the software, and make sure that what-the-duck does not complain about any missing package.

(Ignore what-the-duck‘s errors about things that are not set up yet, like users.)

Creating the image

✎🔗

You may now want to create an image that you can share with your friends. They will think you are cool because they won’t have to duplicate all of the work that you just did. Luckily this is easy. Just power down the duckiebot with:

duckiebot $ sudo shutdown -h now

and put the SD card back in your laptop.

The procedure of how to burn an image is explained in Section 78.1; except you will invert the if and of destinations.

You may want to subsequently shrink the image, for example if your friends have smaller SD cards than you.

The procedure of how to shrink an image is explained in Section 78.2.

Some additions since last image to add in the next image

✎🔗

Note here the additions since the last image was created.

Install Git LFS.

Create a file

/etc/duckietown-image.yaml

Containing these lines

base: Ubuntu 16.04.2
date: DATE
comments: |
    any comments you have

So that we know which image is currently in used.

Installing Ubuntu on laptops

✎🔗

Andrea

Before you prepare the Duckiebot, you need to have a laptop with Ubuntu installed.

Requirements:

A laptop with free disk space.
Internet connection to download the Ubuntu image.
About ??? minutes.

estimate time

Results:

A laptop ready to be used for Duckietown.

Install Ubuntu

✎🔗

Install Ubuntu 16.04.2.

For instructions, see for example this online tutorial.

On the choice of username: During the installation, create a user for yourself with a username different from ubuntu, which is the default. Otherwise, you may get confused later.

Install useful software

✎🔗

Use etckeeper to keep track of the configuration in /etc:

laptop $ sudo apt install etckeeper

Install ssh to login remotely and the server:

laptop $ sudo apt install ssh

Use byobu:

laptop $ sudo apt install byobu

Use vim:

laptop $ sudo apt install vim

Use htop to monitor CPU usage:

laptop $ sudo apt install htop

Additional utilities for git:

laptop $ sudo apt install git git-extras

Other utilities:

laptop $ sudo apt install avahi-utils ecryptfs-utils

Install ROS

✎🔗

Install ROS on your laptop.

The procedure is given in Section 93.1.

Other suggested software

✎🔗

Redshift

✎🔗

This is Flux for Linux. It is an accessibility/lab safety issue: bright screens damage eyes and perturb sleep [3].

Install redshift and run it.

laptop $ sudo apt install redshift-gtk

Set to “autostart” from the icon.

Installation of the duckuments system

✎🔗

Optional but very encouraged: install the duckuments system. This will allow you to have a local copy of the documentation and easily submit questions and changes.

The procedure is documented in Section 5.4.

Passwordless `sudo`

✎🔗

Set up passwordless sudo.

This procedure is described in Section 14.11.

SSH and Git setup

✎🔗

Basic SSH config

✎🔗

Do the basic SSH config.

The procedure is documented in Section 80.3.

Create key pair for `username`

✎🔗

Next, create a private/public key pair for the user; call it username@robot name.

The procedure is documented in Section 80.5.

Add `username`‘s public key to Github

✎🔗

Add the public key to your Github account.

The procedure is documented in Section 89.3.

If the step is done correctly, this command should succeed:

duckiebot $ ssh -T git@github.com

Local Git setup

✎🔗

Set up Git locally.

The procedure is described in Section 87.3.

Duckiebot Initialization

✎🔗

Andrea

Prerequisites:

An SD card of dimensions at least 32 GB.
A computer with an internet connection, an SD card reader, and 35 GB of free space.
A mounted Duckiebot in configuration D17-C0.

This is the result of Chapter 13.

Result:

A Duckiebot that is ready to use.

What does it mean “ready to use”?.

Acquire and burn the image

✎🔗

On the laptop, download the compressed image at this URL:

https://www.dropbox.com/s/1p4am7erdd9e53r/duckiebot-RPI3-AC-aug10.img.xz?dl=1

The size is 2.5 GB.

You can use:

$ curl -o duckiebot-RPI3-AC-aug10.img.xz URL above

Uncompress the file:

$ xz -d -k duckiebot-RPI3-AC-aug10.img.xz

This will create a file of 32 GB in size.

To make sure that the image is downloaded correctly, compute its hash using the program sha256sum:

$ sha256sum duckiebot-RPI3-AC-aug10.img
2ea79b0fc6353361063c89977417fc5e8fde70611e8afa5cbf2d3a166d57e8cf  duckiebot-ac-aug10.img

Compare the hash that you obtain with the hash above. If they are different, there was some problem in downloading the image.

Next, burn the image on disk.

The procedure of how to burn an image is explained in Section 78.1.

Turn on the Duckiebot

✎🔗

Put the SD Card in the Duckiebot.

Turn on the Duckiebot by connecting the power cable to the battery.

Add figure

Connect the Duckiebot to a network

✎🔗

You can login to the Duckiebot in two ways:

Through an Ethernet cable.
Through a duckietown WiFi network.

In the worst case, you can use an HDMI monitor and a USB keyboard.

Option 1: Ethernet cable

✎🔗

Connect the Duckiebot and your laptop to the same network switch.

Allow 30 s - 1 minute for the DHCP to work.

Option 2: Duckietown network

✎🔗

The Duckiebot connects automatically to a 2.4 GHz network called “duckietown” and password “quackquack”.

Connect your laptop to the same wireless network.

Ping the Duckiebot

✎🔗

To test that the Duckiebot is connected, try to ping it.

The hostname of a freshly-installed duckiebot is duckiebot-not-configured:

laptop $ ping duckiebot-not-configured.local

You should see output similar to the following:

PING duckiebot-not-configured.local (X.X.X.X): 56 data bytes
64 bytes from X.X.X.X: icmp_seq=0 ttl=64 time=2.164 ms
64 bytes from X.X.X.X: icmp_seq=1 ttl=64 time=2.303 ms
...

SSH to the Duckiebot

✎🔗

Next, try to log in using SSH, with account ubuntu:

laptop $ ssh ubuntu@duckiebot-not-configured.local

The password is ubuntu.

By default, the robot boots into Byobu.

Please see Chapter 86 for an introduction to Byobu.

Not sure it’s a good idea to boot into Byobu.

(For D17-C1) Configure the robot-generated network

✎🔗

D17-0+w The Duckiebot in configuration D17-C0+w can create a WiFi network.

It is a 5 GHz network; this means that you need to have a 5 GHz WiFi adapter in your laptop.

First, make sure that the Edimax is correctly installed. Using iwconfig, you should see four interfaces:

duckiebot $ iwconfig
wlxAABBCCDDEEFFGG  unassociated  Nickname:"rtl8822bu"

...

lo        no wireless extensions.

enxb827eb1f81a4  no wireless extensions.

wlan1     IEEE 802.11bgn  ESSID:"duckietown"

...

Make note of the name wlxAABBCCDDEEFFGG.

Look up the MAC address using the command:

duckiebot $ ifconfig wlxAABBCCDDEEFFGG
wlx74da38c9caa0 Link encap:Ethernet  HWaddr AA:BB:CC:DD:EE:FF:GG

Then, edit the connection file

/etc/NetworkManager/system-connections/create-5ghz-network

Make the following changes:

Where it says interface-name=..., put “wlxAABBCCDDEEFFGG”.
Where it says mac-address=..., put “AA:BB:CC:DD:EE:FF:GG”.
Where it says ssid=duckiebot-not-configured, put “ssid=robot name”.

Reboot.

At this point you should see a new network being created named “robot name”.

You can connect with the laptop to that network.

If the Raspberry Pi’s network interface is connected to the duckietown network and to the internet, the Raspberry Pi will act as a bridge to the internet.

Setting up wireless network configuration

✎🔗

This part should not be necessary anymore

The Duckiebot is configured by default to connect to a wireless network with SSID duckietown. If that is not your SSID then you will need to change the configuration.

You can add a new network by editing the file:

/etc/wpa_supplicant/wpa_supplicant.conf

You will see a block like the following:

network={
 ssid="duckietown"
 scan_ssid=1
 psk="quackquack"
 priority=10
}

Add a new one with your SSID and password.

This assumes you have a roughly similar wireless network setup - if not then you might need to change some of the other attributes.

Update the system

✎🔗

Next, we need to update to bring the system up to date.

Use these commands

duckiebot $ sudo apt update
duckiebot $ sudo apt dist-upgrade

Give a name to the Duckiebot

✎🔗

It is now time to give a name to the Duckiebot.

These are the criteria:

It should be a simple alphabetic string (no numbers or other characters like “-”, “_”, etc.) .
It will always appear lowercase.
It cannot be a generic name like “duckiebot”, “robot” or similar.

From here on, we will refer to this string as “robot name”. Every time you see robot name, you should substitute the name that you chose.

Change the hostname

✎🔗

We will put the robot name in configuration files.

Files in /etc are only writable by root, so you need to use sudo to edit them. For example:

duckiebot $ sudo vi filename

Edit the file

/etc/hostname

and put “robot name” instead of duckiebot-not-configured.

Also edit the file

/etc/hosts

and put “robot name” where duckiebot-not-configured appears.

The first two lines of /etc/hosts should be:

127.0.0.1   localhost
127.0.1.1   robot name

there is a command hostname that promises to change the hostname. However, the change given by that command does not persist across reboots. You need to edit the files above for the changes to persist.

Never add other hostnames in /etc/hosts. It is a tempting fix when DNS does not work, but it will cause other problems subsequently.

Then reboot the Raspberry Pi using the command

$ sudo reboot

After reboot, log in again, and run the command hostname to check that the change has persisted:

$ hostname
robot name

Expand your filesystem

✎🔗

If your SD card is larger than the image, you’ll want to expand the filesystem on your robot so that you can use all of the space available. Achieve this with:

duckiebot $ sudo raspi-config --expand-rootfs

and then reboot

duckiebot $ sudo shutdown -r now

once rebooted you can test whether this was successful by doing

duckiebot $ df -lh

the output should give you something like:

Filesystem      Size  Used Avail Use% Mounted on
/dev/root        29G  7.8G   21G  28% /
devtmpfs        427M     0  427M   0% /dev
tmpfs           432M  316K  431M   1% /dev/shm
tmpfs           432M   12M  420M   3% /run
tmpfs           5.0M  4.0K  5.0M   1% /run/lock
tmpfs           432M     0  432M   0% /sys/fs/cgroup
/dev/mmcblk0p1   63M   21M   43M  34% /boot
tmpfs            87M   24K   87M   1% /run/user/1000
/dev/sda1        29G  5.3G   24G  19% /media/ubuntu/44A7-9E91

You should see that the Size of your /dev/sda1 partition is “close” to the side of your SD card.

Create your user

✎🔗

You must not use the ubuntu user for development. Instead, you need to create a new user.

Choose a user name, which we will refer to as username.

To create a new user:

duckiebot $ sudo useradd -m username

Make the user an administrator by adding it to the group sudo:

duckiebot $ sudo adduser username sudo

Make the user a member of the group input and i2c

duckiebot $ sudo adduser username input
duckiebot $ sudo adduser username video
duckiebot $ sudo adduser username i2c

Set the shell bash:

duckiebot $ sudo chsh -s /bin/bash andrea

To set a password, use:

duckiebot $ sudo passwd username

At this point, you should be able to login to the new user from the laptop using the password:

laptop $ ssh username@robot name

Next, you should repeat some steps that we already described.

Basic SSH config

✎🔗

Do the basic SSH config.

The procedure is documented in Section 80.3.

Create key pair for `username`

✎🔗

Next, create a private/public key pair for the user; call it username@robot name.

The procedure is documented in Section 80.5.

Add `username`‘s public key to Github

✎🔗

Add the public key to your Github account.

The procedure is documented in Section 89.3.

If the step is done correctly, this command should succeed:

duckiebot $ ssh -T git@github.com

Local Git configuration

✎🔗

This procedure is in Section 87.3.

Set up the laptop-Duckiebot connection

✎🔗

Make sure that you can login passwordlessly to your user from the laptop.

The procedure is explained in Section 80.6. In this case, we have: local = laptop, local-user = your local user on the laptop, remote = robot name, remote-user = username.

If the step is done correctly, you should be able to login from the laptop to the robot, without typing a password:

laptop $ ssh username@robot name

Some advice on the importance of passwordless access

✎🔗

In general, if you find yourself:

typing an IP
typing a password
typing ssh more than once
using a screen / USB keyboard

it means you should learn more about Linux and networks, and you are setting yourself up for failure.

Yes, you “can do without”, but with an additional 30 seconds of your time. The 30 seconds you are not saving every time are the difference between being productive roboticists and going crazy.

Really, it is impossible to do robotics when you have to think about IPs and passwords…

Other customizations

✎🔗

If you know what you are doing, you are welcome to install and use additional shells, but please keep Bash as be the default shell. This is important for ROS installation.

For the record, our favorite shell is ZSH with oh-my-zsh.

Hardware check: camera

✎🔗

Check that the camera is connected using this command:

duckiebot $ vcgencmd get_camera
supported=1 detected=1

If you see detected=0, it means that the hardware connection is not working.

You can test the camera right away using a command-line utility called raspistill.

Use the raspistill command to capture the file out.jpg:

duckiebot $ raspistill -t 1 -o out.jpg

Then download out.jpg to your computer using scp for inspection.

For instructions on how to use scp, see Subsection 82.1.1.

Troubleshooting

✎🔗

detected=0

If you see detected=0, it is likely that the camera is not connected correctly.

If you see an error that starts like this:

mmal: Cannot read camera info, keeping the defaults for OV5647
...
mmal: Camera is not detected. Please check carefully the camera module is installed correctly.

then, just like it says: “Please check carefully the camera module is installed correctly.”.

Software setup and RC remote control

✎🔗

Andrea

Prerequisites:

You have configured the laptop.

The procedure is documented in Chapter 15.

You have configured the Duckiebot.

The procedure is documented in Chapter 16.

You have created a Github account and configured public keys, both for the laptop and for the Duckiebot.

The procedure is documented in Chapter 89.

Results:

You can run the joystick demo.

Clone the Duckietown repository

✎🔗

Clone the repository in the directory ~/duckietown:

duckiebot $ git clone git@github.com:duckietown/Software.git ~/duckietown

For the above to succeed you should have a Github account already set up.

It should not ask for a password.

Troubleshooting

✎🔗

It asks for a password.

You missed some of the steps described in Chapter 89.

Other weird errors.

Probably the time is not set up correctly. Use ntpdate as above:

$ sudo ntpdate -u us.pool.ntp.org

Set up ROS environment on the Duckiebot

✎🔗

All the following commands should be run in the ~/duckietown directory:

duckiebot $ cd ~/duckietown

Now we are ready to make the workspace. First you need to source the baseline ROS environment:

duckiebot $ source /opt/ros/kinetic/setup.bash

Then, build the workspace using:

duckiebot $ catkin_make -C catkin_ws/

For more information about catkin_make, see Subsection 93.5.3.

AC: I had to run it twice. The first time it complained:

In file included from /home/andrea/duckietown/catkin_ws/src/apriltags_ros/apriltags_ros/src/apriltag_detector.cpp:1:0:
/home/andrea/duckietown/catkin_ws/src/apriltags_ros/apriltags_ros/include/apriltags_ros/apriltag_detector.h:6:41: fatal error: duckietown_msgs/BoolStamped.h: No such file or directory

Add your vehicle to the machines file

✎🔗

Automate this part

On the robot edit the file

~/duckietown/catkin_ws/src/duckietown/machines

You will see something like this:

<launch>
    <arg name="env_script_path" default="~/duckietown/environment.sh"/>

    <machine name="robot name" address="robot name.local" user="username"
             env-loader="$(arg env_script_path)"/>
        ...
    ...
</launch>

Now, duplicate a <machine> line between <launch> and </launch>, and replace the name and address string with the name of your vehicle.

For example, for Andrea, robot name = emma and username = andrea. So, he would add this line:

<machine name="emma" address="emma.local" user="andrea" env-loader="$(arg env_script_path)"/>

Commit and push the new machines file. ( No, don’t commit the machines file.)

Test that the joystick is detected

✎🔗

Plug the joystick receiver in one of the USB port on the Raspberry Pi.

To make sure that the joystick is detected, run:

duckiebot $ ls /dev/input/

and check if there is a device called js0 on the list.

Make sure that your user is in the group input and i2c:

duckiebot $ groups
username sudo input i2c

If input and i2c are not in the list, you missed a step. Ohi ohi! You are not following the instructions carefully!

Consult again Section 16.12.

To test whether or not the joystick itself is working properly, run:

duckiebot $ jstest /dev/input/js0

Move the joysticks and push the buttons. You should see the data displayed change according to your actions.

Run the joystick demo

✎🔗

SSH into the Raspberry Pi and run the following from the duckietown directory:

duckiebot $ cd ~/duckietown
duckiebot $ source environment.sh

The environment.sh setups the ROS environment at the terminal (so you can use commands like rosrun and roslaunch).

Now make sure the motor shield is connected.

Run the command:

duckiebot $ roslaunch duckietown joystick.launch veh:=robot name

If there is no “red” output in the command line then pushing the left joystick knob controls throttle - right controls steering.

This is the expected result of the commands:

left joystick up	forward
left joystick down	backward
right joystick left	turn left (positive yaw)
right joystick right	turn right (negative yaw)

It is possible you will have to unplug and replug the joystick or just push lots of buttons on your joystick until it wakes up. Also make sure that the mode switch on the top of your joystick is set to “X”, not “D”.

Is all of the above valid with the new joystick?

Close the program using Ctrl-C.

Troubleshooting

✎🔗

The robot moves weirdly (e.g. forward instead of backward).

The cables are not correctly inserted. Please refer to the assembly guide for pictures of the correct connections. Try swapping cables until you obtain the expected behavior.

Check that the joystick has the switch set to the position “x”.And the mode light should be off.

The left joystick does not work.

If the green light on the right to the “mode” button is on, click the “mode” button to turn the light off. The “mode” button toggles between left joystick or the cross on the left.

The robot does not move at all.

The cables are disconnected.

The program assumes that the joystick is at /dev/input/js0. In doubt, see Section 17.4.

The proper shutdown procedure for the Raspberry Pi

✎🔗

Generally speaking, you can terminate any roslaunch command with Ctrl-C.

To completely shutdown the robot, issue the following command:

duckiebot $ sudo shutdown -h now

Then wait 30 seconds.

If you disconnect the power before shutting down properly using shutdown, the system might get corrupted.

Then, disconnect the power cable, at the battery end.

If you disconnect frequently the cable at the Raspberry Pi’s end, you might damage the port.

Reading from the camera

✎🔗

Prerequisites:

You have configured the Duckiebot.

The procedure is documented in Chapter 16.

You know the basics of ROS (launch files, roslaunch, topics, rostopic).

put reference

Results:

You know that the camera works under ROS.

Check the camera hardware

✎🔗

It might be useful to do a quick camera hardware check.

The procedure is documented in Section 16.14.

Create two windows

✎🔗

On the laptop, create two Byobu windows.

A quick reference about Byobu commands is in Chapter 86.

You will use the two windows as follows:

In the first window, you will launch the nodes that control the camera.
In the second window, you will launch programs to monitor the data flow.

You could also use multiple terminals instead of one terminal with multiple Byobu windows. However, using Byobu is the best practice to learn.

First window: launch the camera nodes

✎🔗

In the first window, we will launch the nodes that control the camera.

Activate ROS:

duckiebot $ source environment.sh

Run the launch file called camera.launch:

duckiebot $ roslaunch duckietown camera.launch veh:=robot name

At this point, you should see the red LED on the camera light up continuously.

In the terminal you should not see any red message, but only happy messages like the following:

...
[INFO] [1502539383.948237]: [/robot name/camera_node] Initialized.
[INFO] [1502539383.951123]: [/robot name/camera_node] Start capturing.
[INFO] [1502539384.040615]: [/robot name/camera_node] Published the first image.

For more information about roslaunch and “launch files”, see Section 93.3.

Second window: view published topics

✎🔗

Switch to the second window.

Activate the ROS environment:

duckiebot $ source environment.sh

List topics

✎🔗

You can see a list of published topics with the command:

duckiebot $ rostopic list

For more information about rostopic, see Section 93.5.

You should see the following topics:

/robot name/camera_node/camera_info
/robot name/camera_node/image/compressed
/robot name/camera_node/image/raw
/rosout
/rosout_agg

Show topics frequency

✎🔗

You can use rostopic hz to see the statistics about the publishing frequency:

laptop $ rostopic hz /robot name/camera_node/image/compressed

On a Raspberry Pi 3, you should see a number close to 30 Hz:

average rate: 30.016
    min: 0.026s max: 0.045s std dev: 0.00190s window: 841

Show topics data

✎🔗

You can view the messages in real time with the command rostopic echo:

laptop $ rostopic echo /robot name/camera_node/image/compressed

You should see a large sequence of numbers being printed to your terminal.

That’s the “image” — as seen by a machine.

If you are Neo, then this already makes sense. If you are not Neo, in Chapter 20, you will learn how to visualize the image stream on the laptop using rviz.

use Ctrl-C to stop rostopic.

RC control launched remotely

✎🔗

Andrea

Prerequisites:

You can run the joystick demo from the Raspberry Pi.

The procedure is documented in Chapter 17.

Results:

You can run the joystick demo from your laptop.

Two ways to launch a program

✎🔗

ROS nodes can be launched in two ways:

“local launch”: log in to the Raspberry Pi using SSH and run the program from there.
“remote launch”: run the program directly from a laptop.

Which is better when is a long discussion that will be done later. Here we set up the “remote launch”.

draw diagrams

Download and setup `Software` repository on the laptop

✎🔗

As you did on the Duckiebot, you should clone the Software repository in the ~/duckietown directory.

The procedure is documented in Section 17.1.

Then, you should build the repository.

This procedure is documented in Section 17.2.

Edit the `machines` files on your laptop

✎🔗

You have to edit the machines files on your laptop, as you did on the Duckiebot.

The procedure is documented in Section 17.3.

Start the demo

✎🔗

Now you are ready to launch the joystick demo remotely.

Make sure that you can login with SSH without a password. From the laptop, run:

laptop $ ssh username@robot name.local

If this doesn’t work, you missed some previous steps.

Run this on the laptop:

laptop $ source environment.sh
laptop $ roslaunch duckietown joystick.launch veh:=robot name

You should be able to drive the vehicle with joystick just like the last example. Note that remotely launching nodes from your laptop doesn’t mean that the nodes are running on your laptop. They are still running on the Raspberry Pi in this case.

For more information about roslaunch, see Section 93.3.

Watch the program output using `rqt_console`

✎🔗

Also, you might have notice that the terminal where you launch the launch file is not printing all the printouts like the previous example. This is one of the limitation of remote launch.

Don’t worry though, we can still see the printouts using rqt_console.

On the laptop, open a new terminal window, and run:

laptop $ export ROS_MASTER_URI=http://robot name.local:11311/
laptop $ rqt_console

AC: I could not see any messages in rqt_console - not sure what is wrong.

You should see a nice interface listing all the printouts in real time, completed with filters that can help you find that message you are looking for in a sea of messages.

You can use Ctrl-C at the terminal where roslaunch was executed to stop all the nodes launched by the launch file.

For more information about rqt_console, see Section 93.2.

Troubleshooting

✎🔗

roslaunch fails with an error similar to the following:

remote[robot name.local-0]: failed to launch on robot name:

Unable to establish ssh connection to [username@robot name.local:22]:
Server u'robot name.local' not found in known_hosts.

You have not followed the instructions that told you to add the HostKeyAlgorithms option. Delete ~/.ssh/known_hosts and fix your configuration.

The procedure is documented in Section 80.3.

RC+camera remotely

✎🔗

Andrea

Prerequisites:

You can run the joystick demo remotely.

The procedure is documented in Chapter 19.

You can read the camera data from ROS.

The procedure is documented in Chapter 18.

You know how to get around in Byobu.

You can find the Byobu tutorial in Chapter 86.

Results:

You can run the joystick demo from your laptop and see the camera image on the laptop.

Assumptions

✎🔗

We are assuming that the joystick demo in Chapter 19 worked.

We are assuming that the procedure in Chapter 18 succeeded.

We also assume that you terminated all instances of roslaunch with Ctrl-C, so that currently there is nothing running in any window.

Terminal setup

✎🔗

On the laptop, this time create four Byobu windows.

A quick reference about Byobu commands is in Chapter 86.

You will use the four windows as follows:

In the first window, you will run the joystick demo, as before.
In the second window, you will launch the nodes that control the camera.
In the third window, you will launch programs to monitor the data flow.
In the fourth window, you will use rviz to see the camera image.

Add figures

First window: launch the joystick demo

✎🔗

In the first window, launch the joystick remotely using the same procedure in Section 19.4.

laptop $ source environment.sh
laptop $ roslaunch duckietown joystick.launch veh:=robot name

You should be able to drive the robot with the joystick at this point.

Second window: launch the camera nodes

✎🔗

In the second window, we will launch the nodes that control the camera.

The launch file is called camera.launch:

laptop $ source environment.sh
laptop $ roslaunch duckietown camera.launch veh:=robot name

You should see the red led on the camera light up.

Third window: view data flow

✎🔗

Open a third terminal on the laptop.

You can see a list of topics currently on the ROS_MASTER with the commands:

laptop $ source environment.sh
laptop $ export ROS_MASTER_URI=http://robot name.local:11311/
laptop $ rostopic list

You should see the following:

/diagnostics
/robot name/camera_node/camera_info
/robot name/camera_node/image/compressed
/robot name/camera_node/image/raw
/robot name/joy
/robot name/wheels_driver_node/wheels_cmd
/rosout
/rosout_agg

Fourth window: visualize the image using `rviz`

✎🔗

Launch rviz by using these commands:

laptop $ source environment.sh
laptop $ source set_ros_master.sh robot name
laptop $ rviz

For more information about rviz, see Section 93.4.

In the rviz interface, click “Add” on the lower left, then the “By topic” tag, then select the “Image” topic by the name

/robot name/camera_node/image/compressed

Then click “ok”. You should be able to see a live stream of the image from the camera.

Proper shutdown procedure

✎🔗

To stop the nodes: You can stop the node by pressing Ctrl-C on the terminal where roslaunch was executed. In this case, you can use Ctrl-C in the terminal where you launched the camera.launch.

You should see the red light on the camera turn off in a few seconds.

Note that the joystick.launch is still up and running, so you can still drive the vehicle with the joystick.

Interlude: Ergonomics

✎🔗

Andrea

So far, we have been spelling out all commands for you, to make sure that you understand what is going on.

Now, we will tell you about some shortcuts that you can use to save some time.

in the future you will have to debug problems, and these problems might be harder to understand if you rely blindly on the shortcuts.

Results:

You will know about some useful shortcuts.

`set_ros_master.sh`

✎🔗

Instead of using:

$ export ROS_MASTER_URI=http://robot name.local:11311/

You can use the “set_ros_master.sh” script in the repo:

$ source set_ros_master.sh robot name

Note that you need to use source; without that, it will not work.

SSH aliases

✎🔗

Instead of using

$ ssh username@robot name.local

You can set up SSH so that you can use:

$ ssh my-robot

To do this, create a host section in ~/.ssh/config with the following contents:

Host my-robot
    User username
    Hostname robot name.local

Here, you can choose any other string in place of “my-robot”.

Note that you cannot do

$ ping my-robot

You haven’t created another hostname, just an alias for SSH.

However, you can use the alias with all the tools that rely on SSH, including rsync and scp.

Wheel calibration

✎🔗

Andrea

Camera calibration

✎🔗

Taking a log

✎🔗

Andrea

Operation manual - Duckietowns

✎🔗

Duckietown parts

✎🔗

Jacopo

Duckietown Assembly

✎🔗

Shiying

The Duckietown specification

✎🔗

Liam?

Topology

✎🔗

Topology constraints

✎🔗

Signs placement

✎🔗

Traffic lights

✎🔗

Operation manual - Duckiebot with LEDs

✎🔗

`D17-1` (LEDs) parts

✎🔗

Jacopo

`D17-1` (LEDs) assembly

✎🔗

Shiying

`D17-1` (LEDs) setup

✎🔗

Andrea

Theory chapters

✎🔗

These are the theory chapters.

Chapter template

✎🔗

Jacopo

Symbols and conventions

✎🔗

Andrea

Conventions

✎🔗

If $x$ is a function of time, use $x_t$ rather than $x(t)$.

Consider the function $x(t)$.

Consider the function $x_t$.

Table of symbols

✎🔗

Here are some useful symbols.

Spaces

command	result
`\SOthree`	$\SOthree$	Rotation matrices
`\SEthree`	$\SEthree$	Euclidean group
`\SEtwo`	$\SEtwo$	Euclidean group
`\setwo`	$\setwo$	Euclidean group algebra

States and poses:

Poses and states

command	result
`\pose`	$\pose_t \in \SEtwo$	Pose of the robot in the plane
`\state_t \in \statesp`	$\state_t \in \statesp$	System state (includes the pose, and everything else)

Linear algebra

✎🔗

Jacopo

Probability basics

✎🔗

Liam?

Dynamics

✎🔗

Jacopo

Autonomy overview

✎🔗

Liam

Perception, planning, control

✎🔗

Autonomy architectures

✎🔗

Andrea

Representations

✎🔗

Matt

Software architectures and middlewares

✎🔗

Andrea

Modern signal processing

✎🔗

Andrea

Basic Kinematics

✎🔗

Jacopo

Basic Dynamics

✎🔗

Jacopo

Odometry Calibration

✎🔗

Jacopo

Computer vision basics

✎🔗

Matt

Illumination invariance

✎🔗

Matt

Line Detection

✎🔗

Matt

Feature extraction

✎🔗

Matt

Place recognition

✎🔗

Matt

Filtering 1

✎🔗

Liam

Filtering 2

✎🔗

Liam

Mission planning

✎🔗

ETH

Planning in discrete domains

✎🔗

ETH

Motion planning

✎🔗

ETH

RRT

✎🔗

ETH

Feedback control

✎🔗

Jacopo

PID Control

✎🔗

Jacopo

MPC Control

✎🔗

Jacopo

Object detection

✎🔗

Nick and David

Object classification

✎🔗

Nick and David

Object tracking

✎🔗

Nick and David

Reacting to obstacles

✎🔗

Jacopo

Semantic segmentation

✎🔗

Nick and David

Text recognition

✎🔗

Nick

SLAM - Problem formulation

✎🔗

Liam

SLAM - Broad categories

✎🔗

Liam

VINS

✎🔗

Liam

Advanced place recognition

✎🔗

Liam

Fleet level planning (placeholder)

✎🔗

ETH

Fleet level planning (placeholder)

✎🔗

ETH

Bibliography

✎🔗

Jacopo Tani, Liam Paull, Maria Zuber, Daniela Rus, Jonathan How, John Leonard, and Andrea Censi. Duckietown: an innovative way to teach autonomy. In EduRobotics 2016. Athens, Greece, December 2016.

pdf

supp. materialbibtex

@inproceedings{tani16duckietown,
        author = “Tani, Jacopo and Paull, Liam and Zuber, Maria and Rus, Daniela and How, Jonathan and Leonard, John and Censi, Andrea”,
        title = “Duckietown: an Innovative Way to Teach Autonomy”,
        url = “http://duckietown.mit.edu/”,
        booktitle = “EduRobotics 2016”,
        year = “2016”,
        month = “December”,
        address = “Athens, Greece”,
        pdf = “http://people.csail.mit.edu/lpaull/publications/Tani_EDU_2016.pdf”
    }

Liam Paull, Jacopo Tani, Heejin Ahn, Javier Alonso-Mora, Luca Carlone, Michal Cap, Yu Fan Chen, Changhyun Choi, Jeff Dusek, Daniel Hoehener, Shih-Yuan Liu, Michael Novitzky, Igor Franzoni Okuyama, Jason Pazis, Guy Rosman, Valerio Varricchio, Hsueh-Cheng Wang, Dmitry Yershov, Hang Zhao, Michael Benjamin, Christopher Carr, Maria Zuber, Sertac Karaman, Emilio Frazzoli, Domitilla Del Vecchio, Daniela Rus, Jonathan How, John Leonard, and Andrea Censi. Duckietown: an open, inexpensive and flexible platform for autonomy education and research. In IEEE International Conference on Robotics and Automation (ICRA). Singapore, May 2017.

pdf

supp. materialbibtex

@inproceedings{paull17duckietown,
        author = “Paull, Liam and Tani, Jacopo and Ahn, Heejin and Alonso-Mora, Javier and Carlone, Luca and Cap, Michal and Chen, Yu Fan and Choi, Changhyun and Dusek, Jeff and Hoehener, Daniel and Liu, Shih-Yuan and Novitzky, Michael and Okuyama, Igor Franzoni and Pazis, Jason and Rosman, Guy and Varricchio, Valerio and Wang, Hsueh-Cheng and Yershov, Dmitry and Zhao, Hang and Benjamin, Michael and Carr, Christopher and Zuber, Maria and Karaman, Sertac and Frazzoli, Emilio and Vecchio, Domitilla Del and Rus, Daniela and How, Jonathan and Leonard, John and Censi, Andrea”,
        title = “Duckietown: an Open, Inexpensive and Flexible Platform for Autonomy Education and Research”,
        url = “http://duckietown.mit.edu/”,
        booktitle = “IEEE International Conference on Robotics and Automation (ICRA)”,
        year = “2017”,
        month = “May”,
        address = “Singapore”,
        pdf = “http://people.csail.mit.edu/lpaull/publications/Paull_ICRA_2017.pdf”
    }

Tosini, G., Ferguson, I., Tsubota, K. Effects of blue light on the circadian system and eye physiology. Molecular Vision, 22, 61–72, 2016 (online).

Exercises

✎🔗

These are the exercises.

ROS tutorial

✎🔗

Line detection

✎🔗

Data processing

✎🔗

Git and conventions

✎🔗

Software manuals

✎🔗

This part describes things that you should know about UNIX/Linux environments.

Please read the “background reading” section before you start, while the rest can be used as a reference.

Documentation writers: please make sure that every command used has a section in these chapters.

Ubuntu packaging with APT

✎🔗

`apt install`

✎🔗

to write

`apt update`

✎🔗

to write

`apt dist-upgrade`

✎🔗

hold back packages

GNU/Linux general notions

✎🔗

Andrea

Background reading

✎🔗

UNIX
Linux
free software; open source software.

`pgrep`

✎🔗

to write

Linux resources usage

✎🔗

Measuring CPU usage using `htop`

✎🔗

You can use htop to monitor CPU usage.

$ sudo apt install htop

to write

Measuring I/O usage using `iotop`

✎🔗

Install using:

$ sudo apt install iotop

to write

How fast is the SD card?

✎🔗

Subsection 78.0.1.

SD Cards tools

✎🔗

Testing SD Card and disk speed

✎🔗

Test SD Card (or any disk) speed using the following commands, which write to a file called filename.

$ dd if=/dev/zero of=filename bs=500K count=1024
$ sync
$ echo 3 | sudo tee /proc/sys/vm/drop_caches
$ dd if=filename of=/dev/null bs=500K count=1024
$ rm filename

Note the sync and the echo command are very important.

Example results:

524288000 bytes (524 MB, 500 MiB) copied, 30.2087 s, 17.4 MB/s
524288000 bytes (524 MB, 500 MiB) copied, 23.3568 s, 22.4 MB/s

That is write 17.4 MB/s, read 22 MB/s.

How to burn an image to an SD card

✎🔗

Requires:

A blank SD card.
An image file to burn.
An Ubuntu computer with an SD reader.

Results:

A burned image.

Finding your device name for the SD card

✎🔗

First, find out what is the device name for the SD card.

Insert the SD Card in the slot.

Run the command:

$ sudo fdisk -l

Find your device name, by looking at the sizes.

For example, the output might contain:

Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes

In this case, the device is /dev/mmcblk0. That will be the device in the next commands.

You may see /dev/mmcblk0pX or a couple of similar entries for each partition on the card, where X is the partition number. If you don’t see anything like that, take out the SD card and run the command again and see what disappeared.

Unmount partitions

✎🔗

Before proceeding, unmount all partitions.

Run df -h. If there are partitions like /dev/mmcblk0pn, then unmount each of them. For example:

laptop $ sudo umount /dev/mmcblk0p1
laptop $ sudo umount /dev/mmcblk0p2

Burn the image

✎🔗

Now that you know that the device is device, you can burn the image to disk.

Let the image file be image file.

Burn the image using the command dd:

laptop $ sudo dd of=device if=image file status=progress bs=4M

Use the name of the device, without partitions. i.e., /dev/mmcblk0, not /dev/mmcblk0pX.

How to shrink an image

✎🔗

Requires:

An image file to burn.
An Ubuntu computer.

Results:

A shrunk image.

Majority of content taken from here

We are going to use the tool gparted so make sure it’s installed

laptop $ sudo apt-get install gparted

Let the image file be image file. Run the command:

laptop $ sudo fdisk -l image file

It should give you something like:

Device                       Boot  Start      End  Sectors  Size Id Type
duckiebot-RPI3-LP-aug15.img1        2048   131071   129024   63M  c W95 FAT32 (LBA)
duckiebot-RPI3-LP-aug15.img2      131072 21219327 21088256 10.1G 83 Linux

Take note of the start of the Linux partition (in our case 131072), let’s call it start. Now we are going to mount the Linux partition from the image:

laptop $ sudo losetup /dev/loop0 imagename.img -o $((start*512))

and then run gparted:

laptop $ sudo gparted /dev/loop0

In gparted click on the partition and click “Resize” under the “Partition” menu. Resize drag the arrow or enter a size that is equal to the minimum size plus 20MB

This didn’t work well for me - I had to add much more than 20MB for it to work.

Click the “Apply” check mark. Before closing the final screen click through the arrows in the dialogue box to find a line such a “resize2fs -p /dev/loop0 1410048K”. Take note of the new size of your partition. Let’s call it new size.

Now remove the loopback on the 2nd partition and setup a loopback on the whole image and run fdisk:

laptop $ sudo losetup -d /dev/loop0
laptop $ sudo losetup /dev/loop0 image file
laptop $ sudo fdisk /dev/loop0

Command (m for help): *d*
Partition number (1,2, default 2): *2*
Command (m for help): *n*
Partition type
p   primary (1 primary, 0 extended, 3 free)
e   extended (container for logical partitions)
Select (default p): *p*
Partition number (2-4, default 2): *2*
First sector (131072-62521343, default 131072): *start*
Last sector, +sectors or +size{K,M,G,T,P} (131072-62521343, default 62521343): *+new size*

(Note: on the last line to include the + and the K as part of the size.)

Created a new partition 2 of type 'Linux' and of size 10.1 GiB.

Command (m for help): *w*
The partition table has been altered.
Calling ioctl() to re-read partition table.
Re-reading the partition table failed.: Invalid argument

The kernel still uses the old table. The new table will be used at the next reboot or after you run partprobe(8) or kpartx(8).

Disregard the final error.

You partition has now been resized and the partition table has been updated. Now we will remove the loopback and then truncate the end of the image file:

laptop $ fdisk -l /dev/loop0

Device       Boot  Start      End  Sectors  Size Id Type
/dev/loop0p1        2048   131071   129024   63M  c W95 FAT32 (LBA)
/dev/loop0p2      131072 21219327 21088256 10.1G 83 Linux

Note down the end of the second partition (in thise case 21219327). Call this end.

laptop $ sudo losetup -d /dev/loop0
laptop $ sudo truncate -s $(((end+1)*512)) image file

You now have a shrunken image file. A further idea is to compress it:

laptop $ xz image file

Networking tools

✎🔗

Andrea

Preliminary reading:

Basics of networking, including
- what are IP addresses
- what are subnets
- how DNS works
- how .local names work
- …

(ref to find).

to write

Make sure that you know:

Visualizing information about the network

✎🔗

`ping`: are you there?

✎🔗

to write

`ifconfig`

✎🔗

to write

$ ifconfig

Accessing computers using SSH

✎🔗

Andrea

Background reading

✎🔗

to write

Encryption
Public key authentication

Installation of SSH

✎🔗

This installs the client:

$ sudo apt install ssh

This installs the server:

to write

This enables the server:

to write

Local configuration

✎🔗

The SSH configuration as a client is in the file

~/.ssh/config

Create the directory with the right permissions:

$ mkdir ~/.ssh
$ chmod 0700 ~/.ssh

Then add the following lines:

HostKeyAlgorithms ssh-rsa

The reason is that Paramiko, used by roslaunch, does not support the ECSDA keys.

✎🔗

To log in to a remote computer remote with user remote-user, use:

$ ssh remote-user@remote

Troubleshooting

✎🔗

Symptom: “Offending key error”.

If you get something like this:

Warning: the ECDSA host key for ... differs from the key for the IP address '... '

Offending key for IP in /home/user/.ssh/known_hosts:line

then remove line line in ~/.ssh/known_hosts.

Creating an SSH keypair

✎🔗

This is a step that you will repeat twice: once on the Duckiebot, and once on your laptop.

The program will prompt you for the filename on which to save the file.

Use the convention

/home/username/.ssh/username@host name
/home/username/.ssh/username@host name.pub

where:

username is the current user name that you are using (ubuntu or your chosen one);
host name is the name of the host (the Duckiebot or laptop);

An SSH key can be generated with the command:

$ ssh-keygen -h

The session output will look something like this:

Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa):

At this point, tell it to choose this file:

/home/username/.ssh/username@host name

Then:

Enter passphrase (empty for no passphrase):

Press enter; you want an empty passphrase.

Enter same passphrase again:

Press enter.

Your identification has been saved in /home/username/.ssh/username@host name
Your public key has been saved in /home/username/.ssh/username@host name.pub
The key fingerprint is:
XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX username@host name
The key's randomart image is:
+--[ RSA 2048]----+
|            .    |
|       o   o  .  |
|      o = o  . o |
|       B . .  * o|
|        S o    O |
|         o o  . E|
|          o o  o |
|           o  +  |
|            .. . |
+-----------------+

Note that the program created two files.

The file that contains the private key is

/home/username/.ssh/username@host name

The file that contains the public key has extension .pub:

/home/username/.ssh/username@host name.pub

Next, tell SSH that you want to use this key.

Make sure that the file ~/.ssh/config exists:

$ touch ~/.ssh/config

Add a line containing

IdentityFile PRIVATE_KEY_FILE

(using the filename for the private key).

Check that the config file is correct:

$ cat ~/.ssh/config
...
IdentityFile PRIVATE_KEY_FILE
...

✎🔗

Assumptions:

You have two computers, called “local” and “remote”, with users “local-user” and “remote-user”.
The two computers are on the same network.
You have created a keypair for local-user on local.

This procedure is described in Section 80.5.

Results:

From the local computer, local-user will be able to log in to remote computer without a password.

First, connect the two computers to the same network, and make sure that you can ping remote from local:

local $ ping remote.local

Do not continue if you cannot do this successfully.

If you have created a keypair for local-user, you will have a public key in this file on the local computer:

/home/local-user/.ssh/local-user@local.pub

This file is in the form:

ssh-rsa long list of letters and numbers local-user@local

You will have to copy the contents of this file on the remote computer, to tell it that this key is authorized.

On the remote computer, edit or create the file:

/home/remote-user/.ssh/authorized_keys

and add the entire line as above containing the public key.

Now, from the local computer, try to log in into the remote one:

local $ ssh remote-user@remote

This should succeed, and you should not be asked for a password.

Fixing SSH Permissions

✎🔗

Sometimes, SSH does not work because you have the wrong permissions on some files.

In doubt, these lines fix the permissions for your .ssh directory.

$ chmod 0700 ~/.ssh
$ chmod 0700 ~/.ssh/*

Wireless networking in Linux

✎🔗

`iwconfig`

✎🔗

to write

`iwlist`

✎🔗

Getting a list of WiFi networks

✎🔗

What wireless networks do I have around?

$ sudo iwlist interface scan | grep SSID

Do I have 5 GHz?

✎🔗

Does the interface support 5 GHz channels?

$ sudo iwlist interface freq

Example output:

wlx74da38c9caa0  20 channels in total; available frequencies :
  Channel 01 : 2.412 GHz
  Channel 02 : 2.417 GHz
  Channel 03 : 2.422 GHz
  Channel 04 : 2.427 GHz
  Channel 05 : 2.432 GHz
  Channel 06 : 2.437 GHz
  Channel 07 : 2.442 GHz
  Channel 08 : 2.447 GHz
  Channel 09 : 2.452 GHz
  Channel 10 : 2.457 GHz
  Channel 11 : 2.462 GHz
  Channel 36 : 5.18 GHz
  Channel 40 : 5.2 GHz
  Channel 44 : 5.22 GHz
  Channel 48 : 5.24 GHz
  Channel 149 : 5.745 GHz
  Channel 153 : 5.765 GHz
  Channel 157 : 5.785 GHz
  Channel 161 : 5.805 GHz
  Channel 165 : 5.825 GHz
  Current Frequency:2.437 GHz (Channel 6)

Note that in this example only some 5Ghz channels are supported (36, 40, 44, 48, 149, 153, 157, 161, 165); for example, channel 38, 42, 50 are not supported. This means that you need to set up the router not to use those channels.

Moving files between computers

✎🔗

SCP

✎🔗

to write

Download a file with SCP

✎🔗

to write

RSync

✎🔗

to write

VIM

✎🔗

Andrea

To do quick changes to files, especially when logged remotely, we suggest you use the VI editor, or more precisely, VIM (“VI iMproved”).

External documentation

✎🔗

A VIM tutorial.

Installation

✎🔗

Install like this:

$ sudo apt install vim

Suggested configuration

✎🔗

Suggested ~/.vimrc:

syntax on
set number
filetype plugin indent on
highlight Comment ctermfg=Gray
autocmd FileType python set complete isk+=.,(

Visual mode

✎🔗

to write

Indenting using VIM

✎🔗

Use the > command to indent.

To indent 5 lines, use 5 > >.

To mark a block of lines and indent it, use V.

For example, use VJJ> to indent 3 lines.

Use < to dedent.

Atom

✎🔗

to write

Eclipse

✎🔗

to write

Installing LiClipse

✎🔗

to write

Byobu

✎🔗

Andrea

You need to learn to use Byobu. It will save you much time later.

See the screencast on the website http://byobu.co/.

Alternatives

✎🔗

GNU Screen is fine as well.

Advantages of using Byobu

✎🔗

To write

Installation

✎🔗

On Ubuntu, install using:

$ sudo apt install byobu

Quick command reference

✎🔗

You can change the escape sequence from Ctrl-A to something else by using the configuration tool that appears when you type F9.

Commands to use windows:

Windows

	Using function keys	Using escape sequences
Create new window	`F2`	`Ctrl`-`A` then `C`
Previous window	`F3`
Next window	`F4`
Switch to window		`Ctrl`-`A` then a number
Close window	`F6`
Rename window		`Ctrl`-`A` then `,`

Commands to use panes (windows split in two or more):

Commands for panes

	Using function keys	Using escape sequences
Split horizontally	`Shift`-`F2`	`Ctrl`-`A` then `\|`
Split vertically	`Ctrl`-`F2`	`Ctrl`-`A` then `%`
Switch focus among panes	`Ctrl`-`↑↓←→`	`Ctrl`-`A` then one of `↑↓←→`
Break pane		`Ctrl`-`A` then `!`

Other commands:

Other

	Using function keys	Using escape sequences
Help		`Ctrl`-`A` then `?`
Detach		`Ctrl`-`A` then `D`

Commands on OS X

✎🔗

Scroll up and down using fnoption↑ and fnoption↓.

Highlight using alt

Source code control with Git

✎🔗

Andrea

Background reading

✎🔗

to write

Git
GitFlow

Installation

✎🔗

The basic Git program is installed using

$ sudo apt install git

Additional utilities for git are installed using:

$ sudo apt install git-extras

This include the git-ignore utility.

Setting up global configurations for Git

✎🔗

This should be done twice, once on the laptop, and later, on the robot.

These options tell Git who you are:

$ git config --global user.email "email"
$ git config --global user.name  "full name"

Also do this, and it doesn’t matter if you don’t know what it is:

$ git config --global push.default simple

Git tips

✎🔗

Shallow clone

✎🔗

You can clone without history with the command:

$ git clone --depth 1 repository URL

Git troubleshooting

✎🔗

Problem 1: https instead of ssh:

✎🔗

The symptom is:

$ git push
Username for 'https://github.com':

Diagnosis: the remote is not correct.

If you do git remote you get entries with https::

$ git remote -v
origin  https://github.com/duckietown/Software.git (fetch)
origin  https://github.com/duckietown/Software.git (push)

Expectation:

$ git remote -v
origin  git@github.com:duckietown/Software.git (fetch)
origin  git@github.com:duckietown/Software.git (push)

Solution:

$ git remote remove origin
$ git remote add origin git@github.com:duckietown/Software.git

Problem 1: `git push` complains about upstream

✎🔗

The symptom is:

fatal: The current branch branch name has no upstream branch.

Solution:

$ git push --set-upstream origin branch name

Git LFS

✎🔗

This describes Git LFS.

Generic installation instructions

✎🔗

See instructions at:

https://git-lfs.github.com/

Ubuntu 16 installation (laptop)

✎🔗

Following these instructions, run the following:

$ sudo add-apt-repository ppa:git-core/ppa
$ curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
$ sudo apt update
$ sudo apt-get install git-lfs

Ubuntu 16 Mate installation (Raspberry Pi 3)

✎🔗

unresolved issues.

The instructions above do not work.

Following this, the error that appears is that golang on the Pi is 1.6 instead it should be 1.7.

Troubleshooting

✎🔗

The binaries are not installed.

If you have installed LFS after pulling the repository and you see only the pointer files, do:

$ git lfs pull --all

Setup Github access

✎🔗

Andrea

This chapter describes how to create a Github account and setup SSH on the robot and on the laptop.

Create a Github account

✎🔗

Our example account is the following:

Github name: greta-p
E-mail: greta-p@duckietown.com

Create a Github account (Figure 36).

Go to your inbox and verify the email.

Become a member of the Duckietown organization

✎🔗

Give the administrators your account name. They will invite you.

Accept the invitation to join the organization that you will find in your email.

Add a public key to Github

✎🔗

You will do this procedure twice: once for the public key created on the laptop, and later with the public key created on the robot.

Requires:

A public/private keypair already created and configured.

This procedure is explained in Section 80.5.

Result:

You can access Github using the key provided.

Go to settings (Figure 37).

Add the public key that you created:

To check that all of this works, use the command

$ ssh -T git@github.com

The command tries to connect to Github using the private keys that you specified. This is the expected output:

Warning: Permanently added the RSA host key for IP address 'ip address' to the list of known hosts.
Hi username! You've successfully authenticated, but GitHub does not provide shell access.

If you don’t see the greeting, stop.

Repeat what you just did for the Duckiebot on the laptop as well, making sure to change the name of the file containing the private key.

Duckietown development guide

✎🔗

This part is about how to develop software for the Duckiebot.

Configuration

✎🔗

This chapter explains what are the assumptions about the configuration.

While the “Setup” parts are “imperative” (do this, do that); this is the “declarative” part, which explains what are the properties of a correct configuration (but it does not explain how to get there).

The tool what-the-duck checks these conditions (Chapter 91). If you make a change from the existing conditions, make sure that it gets implemented in what-the-duck by filing an issue.

Environment variables

✎🔗

You need to have set up the variables in Table 14.

Environment variables used by the software

variable	reasonable value	contains
`DUCKIETOWN_ROOT`	`~/duckietown`	`Software` repository
`DUCKIEFLEET_ROOT`	`~/duckiefleet`	A repository that contains `scuderia.yaml` and other team-specific configuration.

Duckietown root directory `DUCKIETOWN_ROOT`

✎🔗

to write

Duckiefleet directory `DUCKIEFLEET_ROOT`

✎🔗

For Fall 2017, this is the the repository duckiefleet-fall2017.

For self-guided learners, this is an arbitrary repository to create.

The scuderia file

✎🔗

In the ${DUCKIEFLEET_ROOT} directory, there needs to exist a file called:

${DUCKIEFLEET_ROOT}/scuderia.yaml

The file must contain YAML entries of the type:

robot-name:
   username: username
   owner_duckietown_id: owner duckietown ID

A minimal example is in Listing 4.

emma:
  username: andrea
  owner_duckietown_id: censi

Minimal scuderia file

Explanations of the fields:

robot name: the name of the robot, also equal to the host name.
username: the name of the Linux user on the robot, from which to run programs.
owner_duckietown_id: the owner’s globally-unique Duckietown ID.

The `machines` file

✎🔗

The machines file is created using:

$ rosrun duckietown create-machines-file

People database

✎🔗

Andrea

Describe the people database; this is the evolution of the yaml files

The globally-unique Duckietown ID

✎🔗

This is a globally-unique ID for people in the Duckietown project.

It is equal to the Slack username.

What the duck!

✎🔗

what-the-duck is a program that tests dozens of configuration inconsistencies that can happen on a Duckiebot.

To use it, first compile the repository, and then run:

$ ./what-the-duck

Adding more tests to `what-the-duck`

✎🔗

The idea is to add to what-the-duck all the tests that can be automated.

The documentation about to do that is not ready yet.

Tests already added

✎🔗

Here’s the list of tests already added:

✓  Camera is detected
✓  Scipy is installed
✓  sklearn is installed
✓  Date is set correctly
✓  Not running as root
✓  Not running as ubuntu
✓  Member of group sudo
✓  Member of group input
✓  Member of group video
✓  Member of group i2c
✓  ~/.ssh exists
✓  ~/.ssh permissions
✓  ~/.ssh/config exists
✓  SSH option HostKeyAlgorithms is set
✓  At least one key is configured.
✓  ~/.ssh/authorized_keys exists
✓  Git configured
✓  Git email set
✓  Git name set
✓  Git push policy set
✓  Edimax detected
✓  The hostname is configured
✓  /etc/hosts is sane
✓  Correct kernel version
✓  Messages are compiled
✓  Shell is bash
✓  Working internet connection
✓  Github configured
✓  Joystick detected
✓  Environment variable DUCKIETOWN_ROOT
✓  ${DUCKIETOWN_ROOT} exists
✓  Environment variable DUCKIETOWN_FLEET
✓  ${DUCKIETOWN_FLEET} exists
✓  ${DUCKIETOWN_FLEET}/scuderia.yaml exists
✓  ${DUCKIETOWN_FLEET}/scuderia.yaml is valid
✓  machines file is valid
✓  Wifi network configured
✓  Python: No CamelCase
✓  Python: No tab chars
✓  Python:  No half merges

List of tests to add

✎🔗

Please add below any configuration test that can be automated:

Editor is set to vim.
They put the right MAC address in the network configuration
Ubuntu user is in group video, input, i2c (even if run from other user.)
There is at least X.YGB of free disk space.
If the SD is larger than 8GB, the disk has been resized.
Done sudo rosdep init

Python

✎🔗

Background reading

✎🔗

Python
Python tutorial

Python virtual environments

✎🔗

Install using:

$ sudo apt install virtualenv

Useful libraries

✎🔗

matplotlib
seaborne
numpy
panda
scipy
opencv
...

Introduction to ROS

✎🔗

Liam

Install ROS

✎🔗

This part installs ROS. You will run this twice, once on the laptop, once on the robot.

The first commands are copied from this page.

Tell Ubuntu where to find ROS:

$ sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

Tell Ubuntu that you trust the ROS people (they are nice folks):

$ sudo apt-key adv --keyserver hkp://ha.pool.sks-keyservers.net:80 --recv-key 421C365BD9FF1F717815A3895523BAEEB01FA116

Fetch the ROS repo:

$ sudo apt update

Now install the mega-package ros-kinetic-desktop-full.

$ sudo apt install ros-kinetic-desktop-full

There’s more to install:

$ sudo apt install ros-kinetic-{tf-conversions,cv-bridge,image-transport,camera-info-manager,theora-image-transport,joy,image-proc,compressed-image-transport,phidgets-drivers,imu-complementary-filter,imu-filter-madgwick}

Do not install packages by the name of ros-X, only those by the name of ros-kinetic-X. The packages ros-X are from another version of ROS.

: not done in aug20 image:

Initialize ROS:

$ sudo rosdep init
$ rosdep update

`rqt_console`

✎🔗

to write

`roslaunch`

✎🔗

to write

`rviz`

✎🔗

to write

`rostopic`

✎🔗

to write

`rostopic hz`

✎🔗

to write

`rostopic echo`

✎🔗

to write

`catkin_make`

✎🔗

to write

Troubleshooting

✎🔗

computer is not in your SSH known_hosts file

See this thread. Remove the known_hosts file and make sure you have followed the instructions in Section 80.3.

How to create a ROS package

✎🔗

Conforming ROS package checklist

✎🔗

☐ The name of the package is package_handle

☐ The directory is in …

☐ The messages are called ….

☐ there is a readme file

☐ there is the first launch file

Integrate package in the architecture

✎🔗

Creating unit tests

✎🔗

Duckietown Software architecture

✎🔗

Fall 2017

✎🔗

This is the first time that a class is taught jointly across 3 continents!

There are 4 universities involved in the joint teaching for the term:

ETH Zürich (ETHZ), with instructors Emilio Frazzoli, Andrea Censi, Jacopo Tani.
University of Montreal (UdeM), with instructor Liam Paull.
TTI-Chicago (TTIC), with instructor Matthew Walter.
National C T University (NCTU), with instructor Nick Wang.

This part of the Duckiebook describes all the information that is needed by the students of the four institutions.

General remarks

✎🔗

Andrea

The rules of Duckietown

✎🔗

The first rule of Duckietown

The first rule of Duckietown is: you don’t talk about Duckietown, using email.

Instead, we use a communication platform called Slack.

There is one exception: inquiries about “meta” level issues, such as course enrollment and other official bureaucratic issues can be communicated via email.

The second rule of Duckietown

The second rule of Duckietown is: be kind and respectful, and have fun.

The third rule of Duckietown

The third rule of Duckietown is: read the instructions carefully.

Do not blindly copy and paste.

Only run a command if you know what it does.

Synchronization between classes

✎🔗

At ETHZ, UdeM, TTIC, the class will be more-or-less synchronized. The materials are the same; there is some slight variation in the ordering.

Moreover, there will be some common groups for the projects.

The NCTU class is undergraduate level. Students will learn slightly simplified materials. They will not collaborate directly with the classes.

Accounts for students

✎🔗

To participate in Duckietown, students must use two accounts: Slack and Github.

Slack

✎🔗

You need a Slack account, for team discussion and organization.

Sign up link here:

Account naming convention

Github

✎🔗

Account naming convention

A Github account;
Membership in the Duckietown organization.

Accounts for all instructors and TAs

✎🔗

As an instructor/TA for the Fall 2017 class, in addition to the accounts above, these are two more accounts that you need.

Twist

✎🔗

Twist is used for class organization (such as TAs, logistics);

TODO:

Google docs

✎🔗

Google Docs is used to maintain TODOs and other coordination materials.

how to be authorized?

In particular:

This is the schedule: XXX
This is the calendar in which to annotate everything: XXX

Additional information for ETH Zürich students

✎🔗

Andrea

This section describes information specific for ETH Zürich students.

to write

Website

✎🔗

All really important information, such as deadlines, is in the authoritative website:

Duckiebox distribution

✎🔗

to write

Lab access

✎🔗

To write

The local TAs

✎🔗

to write

Additional information for UdeM students

✎🔗

Liam

to write

Additional information for TTIC students

✎🔗

Matt

to write

Additional information for NCTU students

✎🔗

Nick

to write

Milestone: ROS node working

✎🔗

Homework: Take and process a log

✎🔗

Milestone: Calibrated robot

✎🔗

Homework: Camera geometry

✎🔗

Milestone: Illumination invariance

✎🔗

Homework: Place recognition

✎🔗

Milestone: Lane following

✎🔗

Homework: localization

✎🔗

Milestone: Navigation

✎🔗

Homework: group forming

✎🔗

Milestone: Ducks in a row

✎🔗

Homework: Comparison of PID

✎🔗

Homework: RRT

✎🔗

Caffe tutorial

✎🔗

Milestone: Object Detection

✎🔗

Homework: Object Detection

✎🔗

Milestone: Semantic perception

✎🔗

Homework: Semantic perception

✎🔗

Milestone: Reacting to obstacles

✎🔗

Homework: Reacting to obstacles

✎🔗

Milestone: SLAM demo

✎🔗

Homework: SLAM

✎🔗

Milestone: fleet demo

✎🔗

Homework: fleet

✎🔗

Project proposals

✎🔗

Template of a project

✎🔗

Checklist for students

✎🔗

Have a Github account. See Chapter 89. See name conventions (TODO).
Be part of the Duckietown Github organization. You are sure only when you commit and push one change to one of our repositories.
Be part of the Duckietown Slack. See name conventions (TODO).

Checklist for TAs

✎🔗

Be signed up on

Drafts or pieces to remove

✎🔗

The Duckietown Book

Table of contents

The Duckietown project

What is Duckietown?

Goals and objectives

Learn about the Duckietown educational experience

Learn about the platform

Duckietown history and future

The beginnings of Duckietown

University-level classes in 2016

University-level classes in 2017

Chile

Duckietown High School

First steps

How to get started

Duckietown for instructors

Duckietown for self-guided learners

Introduction for companies

How to keep in touch

How to contribute

Frequently Asked Questions

General questions

FAQ by students / independent learners

FAQ by instructors

Accounts

Complete list of accounts

For other contributors

How to contribute to Duckietown

Contributing to the documentation

Where the documentation is

Editing links

Comments

Installing the documentation system

Dependencies

Download the duckuments repo

Setup the virtual environment

Setup the mcdp external repository

Compiling the documentation

Incremental compilation

Troubleshooting compilation

The workflow to edit documentation.

*Deploying the documentation

*Compiling the PDF version

Installing nodejs

Troubleshooting nodejs installation problems

Installing Prince

Installing fonts

Compiling the PDF

Features of the documentation writing system

Embedded LaTeX

LaTeX symbols

Variables in command lines and command output

Character escapes

Keyboard keys

Figures

Subfigures

Shortcut for tables

labels-row1 and labels-row1

Linking to documentation from inside and outside the documentation

Establishing names of headers

Linking from the documentation to the documentation

Linking to the documentation from outside the documentation

Embedding videos

Documentation style guide

General guidelines for technical writing

Style guide for the Duckietown documentation

Writing command lines

Frequently misspelled words

Other conventions

Troubleshooting sections

Troubleshooting

Knowledge graph

Formalization

Atoms

Semantic graph of atoms

Modules

Atoms properties

Markdown format for text-like atoms

How to describe the semantic graphs of atoms

How to describe modules

Download the `duckuments` repo

Setup the `mcdp` external repository

Installing `nodejs`

Troubleshooting `nodejs` installation problems

`labels-row1` and `labels-row1`

Acquiring the parts for the Duckiebot `C0`

Soldering boards for `C0`

Assembling the Duckiebot `C0`

Passwordless `sudo`

Create key pair for `username`

Add `username`‘s public key to Github